# Security in AWS IoT Greengrass Cloud security at AWS is the highest priority. As an AWS customer, you benefit from a data center and network architecture that is built to meet the requirements of the most security-sensitive organizations. Security is a shared responsibility between AWS and you. The [shared responsibility model](https://aws.amazon.com/compliance/shared-responsibility-model/) describes this as security *of* the cloud and security *in* the cloud: + **Security of the cloud** – AWS is responsible for protecting the infrastructure that runs AWS services in the AWS Cloud. AWS also provides you with services that you can use securely. Third-party auditors regularly test and verify the effectiveness of our security as part of the [AWS Compliance Programs](https://aws.amazon.com/compliance/programs/). To learn about the compliance programs that apply to AWS IoT Greengrass, see [AWS Services in Scope by Compliance Program](https://aws.amazon.com/compliance/services-in-scope/). + **Security in the cloud** – Your responsibility is determined by the AWS service that you use. You are also responsible for other factors, including the sensitivity of your data, your company's requirements, and applicable laws and regulations. When you use AWS IoT Greengrass, you are also responsible for securing your devices, local network connection, and private keys. This documentation helps you understand how to apply the shared responsibility model when using AWS IoT Greengrass. The following topics show you how to configure AWS IoT Greengrass to meet your security and compliance objectives. You also learn how to use other AWS services that help you to monitor and secure your AWS IoT Greengrass resources. **Topics** + [Data protection in AWS IoT Greengrass](data-protection.md) + [Device authentication and authorization for AWS IoT Greengrass](device-auth.md) + [Identity and access management for AWS IoT Greengrass](security-iam.md) + [Allow device traffic through a proxy or firewall](allow-device-traffic.md) + [Compliance validation for AWS IoT Greengrass](compliance-validation.md) + [FIPS endpoints](FIPS.md) + [Resilience in AWS IoT Greengrass](disaster-recovery-resiliency.md) + [Infrastructure security in AWS IoT Greengrass](infrastructure-security.md) + [Configuration and vulnerability analysis in AWS IoT Greengrass](vulnerability-analysis-and-management.md) + [Code integrity in AWS IoT Greengrass V2](code-integrity.md) + [AWS IoT Greengrass and interface VPC endpoints (AWS PrivateLink)](vpc-interface-endpoints.md) + [Security best practices for AWS IoT Greengrass](security-best-practices.md) + [Run AWS IoT Greengrass V2 as a non-root user](run-greengrass-non-root.md) # Data protection in AWS IoT Greengrass The AWS [shared responsibility model](https://aws.amazon.com/compliance/shared-responsibility-model/) applies to data protection in AWS IoT Greengrass. As described in this model, AWS is responsible for protecting the global infrastructure that runs all of the AWS Cloud. You are responsible for maintaining control over your content that is hosted on this infrastructure. You are also responsible for the security configuration and management tasks for the AWS services that you use. For more information about data privacy, see the [Data Privacy FAQ](https://aws.amazon.com/compliance/data-privacy-faq/). For information about data protection in Europe, see the [AWS Shared Responsibility Model and GDPR](https://aws.amazon.com/blogs/security/the-aws-shared-responsibility-model-and-gdpr/) blog post on the *AWS Security Blog*. For data protection purposes, we recommend that you protect AWS account credentials and set up individual users with AWS IAM Identity Center or AWS Identity and Access Management (IAM). That way, each user is given only the permissions necessary to fulfill their job duties. We also recommend that you secure your data in the following ways: + Use multi-factor authentication (MFA) with each account. + Use SSL/TLS to communicate with AWS resources. We require TLS 1.2 and recommend TLS 1.3. + Set up API and user activity logging with AWS CloudTrail. For information about using CloudTrail trails to capture AWS activities, see [Working with CloudTrail trails](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-trails.html) in the *AWS CloudTrail User Guide*. + Use AWS encryption solutions, along with all default security controls within AWS services. + Use advanced managed security services such as Amazon Macie, which assists in discovering and securing sensitive data that is stored in Amazon S3. + If you require FIPS 140-3 validated cryptographic modules when accessing AWS through a command line interface or an API, use a FIPS endpoint. For more information about the available FIPS endpoints, see [Federal Information Processing Standard (FIPS) 140-3](https://aws.amazon.com/compliance/fips/). We strongly recommend that you never put confidential or sensitive information, such as your customers' email addresses, into tags or free-form text fields such as a **Name** field. This includes when you work with AWS IoT Greengrass or other AWS services using the console, API, AWS CLI, or AWS SDKs. Any data that you enter into tags or free-form text fields used for names may be used for billing or diagnostic logs. If you provide a URL to an external server, we strongly recommend that you do not include credentials information in the URL to validate your request to that server. For more information about protecting sensitive information in AWS IoT Greengrass, see [Don't log sensitive information](security-best-practices.md#protect-pii). For more information about data protection, see the [AWS Shared Responsibility Model and GDPR](https://aws.amazon.com/blogs/security/the-aws-shared-responsibility-model-and-gdpr/) blog post on the *AWS Security Blog*. **Topics** + [Data encryption](data-encryption.md) + [Hardware security integration](hardware-security.md) # Data encryption AWS IoT Greengrass uses encryption to protect data while in-transit (over the internet or local network) and at rest (stored in the AWS Cloud). Devices in a AWS IoT Greengrass environment often collect data that's sent to AWS services for further processing. For more information about data encryption on other AWS services, see the security documentation for that service. **Topics** + [Encryption in transit](encryption-in-transit.md) + [Encryption at rest](encryption-at-rest.md) + [Key management for the Greengrass core device](key-management.md) # Encryption in transit AWS IoT Greengrass has two modes of communication where data is in transit: + [Data in transit over the internet](#data-in-transit-internet). Communication between a Greengrass core and AWS IoT Greengrass over the internet is encrypted. + [Data on the core device](#data-in-transit-locally). Communication between components on the Greengrass core device is not encrypted. ## Data in transit over the internet AWS IoT Greengrass uses Transport Layer Security (TLS) to encrypt all communication over the internet. All data sent to the AWS Cloud is sent over a TLS connection using MQTT or HTTPS protocols, so it is secure by default. AWS IoT Greengrass uses the AWS IoT transport security model. For more information, see [Transport security](https://docs.aws.amazon.com/iot/latest/developerguide/transport-security.html) in the *AWS IoT Core Developer Guide*. ## Data on the core device AWS IoT Greengrass doesn't encrypt data exchanged locally on the Greengrass core device because the data doesn't leave the device. This includes communication between user-defined components, the AWS IoT device SDK, and public components, such as stream manager. # Encryption at rest AWS IoT Greengrass stores your data: + [Data at rest in the AWS Cloud](#data-at-rest-cloud). This data is encrypted. + [Data at rest on the Greengrass core](#data-at-rest-device). This data is not encrypted (except local copies of your secrets). ## Data at rest in the AWS Cloud AWS IoT Greengrass encrypts customer data stored in the AWS Cloud. This data is protected using AWS KMS keys that are managed by AWS IoT Greengrass. ## Data at rest on the Greengrass core AWS IoT Greengrass relies on Unix file permissions and full-disk encryption (if enabled) to protect data at rest on the core. It is your responsibility to secure the file system and device. However, AWS IoT Greengrass does encrypt local copies of your secrets retrieved from AWS Secrets Manager. For more information, see the [secret manager](secret-manager-component.md) component. # Key management for the Greengrass core device It's the responsibility of the customer to guarantee secure storage of cryptographic (public and private) keys on the Greengrass core device. AWS IoT Greengrass uses public and private keys for the following scenario: + The IoT client key is used with the IoT certificate to authenticate the Transport Layer Security (TLS) handshake when a Greengrass core connects to AWS IoT Core. For more information, see [Device authentication and authorization for AWS IoT Greengrass](device-auth.md). **Note** The key and certificate are also referred to as the core private key and the core device certificate. A Greengrass core device supports private key storage using file system permissions or a [hardware security module](hardware-security.md). If you use file system-based private keys, you are responsible for their secure storage on the core device. # Hardware security integration **Note** For [Greengrass nucleus](greengrass-nucleus-component.md), this feature requires v2.5.3 or later. AWS IoT Greengrass doesn't currently support this feature on Windows core devices. [Greengrass nucleus lite](greengrass-nucleus-lite-component.md) v2.5.0 and later include built-in PKCS\$111 support and do not require the PKCS\$111 provider component. You must have an OpenSSL provider configured for your PKCS\$111 device. For more information, see [PKCS\$111 support](https://github.com/aws-greengrass/aws-greengrass-lite/blob/main/docs/PKCS11_SUPPORT.md) in the AWS IoT Greengrass nucleus lite GitHub repository. You can 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 the device's private key and certificate so that they aren't exposed or duplicated in software. You can store the private key and certificate on a hardware module such as an HSM or a Trusted Platform Module (TPM). The AWS IoT Greengrass Core software uses a private key and X.509 certificate to authenticate connections to the AWS IoT and AWS IoT Greengrass services. The [secret manager component](secret-manager-component.md) uses this private key to securely encrypt and decrypt the secrets that you deploy to a Greengrass core device. When you configure a core device to use an HSM, these components use the private key and certificate that you store in the HSM. The [Moquette MQTT broker component](mqtt-broker-moquette-component.md) also stores a private key for its local MQTT server certificate. This component store the private key on the device's file system in the component's work folder. Currently, AWS IoT Greengrass doesn't support storing this private key or certificate in an HSM. **Tip** Search for devices that support this feature in the [AWS Partner Device Catalog](https://devices.amazonaws.com/search?kw=%22HSI%22&page=1). **Topics** + [Requirements](#hardware-security-requirements) + [Hardware security best practices](#hardware-security-best-practices) + [Install the [Greengrass nucleus](greengrass-nucleus-component.md) software with hardware security](#install-with-hardware-security) + [Configure hardware security on an existing [Greengrass nucleus](greengrass-nucleus-component.md) core device](#enable-hardware-security) + [Use hardware without PKCS\$111 support](#hardware-without-pkcs11) + [See also](#hardware-security-see-also) ## Requirements You must meet the following requirements to use an HSM on a Greengrass core device: + [Greengrass nucleus](greengrass-nucleus-component.md) v2.5.3 or later, or [Greengrass nucleus lite](greengrass-nucleus-lite-component.md) v2.5.0 or later, installed on the core device. If you use [Greengrass nucleus lite](greengrass-nucleus-lite-component.md), see [PKCS\$111 support](https://github.com/aws-greengrass/aws-greengrass-lite/blob/main/docs/PKCS11_SUPPORT.md) in the AWS IoT Greengrass nucleus lite GitHub repository for setup instructions. + The [PKCS\$111 provider component](pkcs11-provider-component.md) installed on the core device. You can download and install this component when you install the AWS IoT Greengrass Core software on a core device. + A hardware security module that supports the [PKCS\$11 v1.5](https://tools.ietf.org/html/rfc2313) signature scheme and RSA keys with an RSA-2048 key size (or larger) or ECC keys. **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. + A PKCS\$111 provider library that the AWS IoT Greengrass Core software can load at runtime (using libdl) to invoke PKCS\$111 functions. The PKCS\$111 provider library must implement the following PKCS\$111 API operations: + `C_Initialize` + `C_Finalize` + `C_GetSlotList` + `C_GetSlotInfo` + `C_GetTokenInfo` + `C_OpenSession` + `C_GetSessionInfo` + `C_CloseSession` + `C_Login` + `C_Logout` + `C_GetAttributeValue` + `C_FindObjectsInit` + `C_FindObjects` + `C_FindObjectsFinal` + `C_DecryptInit` + `C_Decrypt` + `C_DecryptUpdate` + `C_DecryptFinal` + `C_SignInit` + `C_Sign` + `C_SignUpdate` + `C_SignFinal` + `C_GetMechanismList` + `C_GetMechanismInfo` + `C_GetInfo` + `C_GetFunctionList` + The hardware module must be resolvable by slot label, as defined in the PKCS\$111 specification. + You must store the private key and certificate in the HSM in the same slot, and they must use the same object label and object ID, if the HSM supports object IDs. + The certificate and private key must be resolvable by object labels. + The private key must have the following permissions: + `sign` + `decrypt` + (Optional) To use the [secret manager component](secret-manager-component.md), you must use version 2.1.0 or later, and the private key must have the following permissions: + `unwrap` + `wrap` ## Hardware security best practices Consider the following best practices when you configure hardware security on Greengrass core devices. + Generate private keys directly on the HSM by using the internal hardware random-number generator. This approach is more secure than importing a private key that you generate elsewhere, because the private key remains within the HSM. + Configure private keys to be immutable and prohibit export. + Use the provisioning tool that the HSM hardware vendor recommends to generate a certifacte signing request (CSR) using the hardware-protected private key, and then use the AWS IoT console or API to generate a client certificate. **Note** The security best practice to rotate keys doesn't apply when you generate private keys on an HSM. ## Install the [Greengrass nucleus](greengrass-nucleus-component.md) software with hardware security When you install the AWS IoT Greengrass Core software, you can configure it to use a private key that you generate in an HSM. This approach follows the [security best practice](#hardware-security-best-practices) to generate the private key in the HSM, so the private key remains within the HSM. To install the AWS IoT Greengrass Core software with hardware security, you do the following: 1. Generate a private key in the HSM. 1. Create a certificate signing request (CSR) from the private key. 1. Create a certificate from the CSR. You can create a certificate signed by AWS IoT or by another root certificate authority (CA). For more information about how to use another root CA, 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*. 1. Download the AWS IoT certificate and import it into the HSM. 1. Install the AWS IoT Greengrass Core software from a configuration file that specifies to use the PKCS\$111 provider component and the private key and certificate in the HSM. You can choose one of the following installation options to install the AWS IoT Greengrass Core software with hardware security: + **Manual installation** Choose this option to manually create the required AWS resources and configure hardware security. For more information, see [Install AWS IoT Greengrass Core software with manual resource provisioning](manual-installation.md). + **Installation with custom provisioning** Choose this option to develop a custom Java application that automatically creates the required AWS resources and configures hardware security. For more information, see [Install AWS IoT Greengrass Core software with custom resource provisioning](custom-provisioning.md). The [Greengrass nucleus](greengrass-nucleus-component.md) doesn't support installing the AWS IoT Greengrass Core software with hardware security when you [install with automatic resource provisioning](quick-installation.md) or [AWS IoT fleet provisioning](fleet-provisioning.md). [Greengrass nucleus lite](greengrass-nucleus-lite-component.md) v2.5.0 and later support hardware security with fleet provisioning. ## Configure hardware security on an existing [Greengrass nucleus](greengrass-nucleus-component.md) core device You can import a core device's private key and certificate to an HSM to configure hardware security. **Considerations** You must have root access to the core device's file system. In this procedure, you shut down the AWS IoT Greengrass Core software, so the core device is offline and unavailable while you configure hardware security. To configure hardware security on an existing core device, you do the following: 1. Initialize the HSM. 1. Deploy the [PKCS\$111 provider component](pkcs11-provider-component.md) to the core device. 1. Stop the AWS IoT Greengrass Core software. 1. Import the core device's private key and certificate to the HSM. 1. Update the AWS IoT Greengrass Core software's configuration file to use the private key and certificate in the HSM. 1. Start the AWS IoT Greengrass Core software. ### Step 1: Initialize the hardware security module Complete the following step to initialize the HSM on your core device. **To initialize the hardware security module** + Initialize an PKCS\$111 token in the HSM, and save the slot ID and user PIN that for the token. Check the documentation for your HSM to learn how to initialize a token. You use the slot ID and user PIN later when you deploy and configure the PKCS\$111 provider component. ### Step 2: Deploy the PKCS\$111 provider component Complete the following steps to deploy and configure the [PKCS\$111 provider component](pkcs11-provider-component.md). You can deploy the component to one or more core devices. #### To deploy the PKCS\$111 provider component (console) 1. In the [AWS IoT Greengrass console](https://console.aws.amazon.com/greengrass) navigation menu, choose **Components**. 1. On the **Components** page, choose the **Public components** tab, and then choose **aws.greengrass.crypto.Pkcs11Provider**. 1. On the **aws.greengrass.crypto.Pkcs11Provider** page, choose **Deploy**. 1. From **Add to deployment**, choose an existing deployment to revise, or choose to create a new deployment, and then choose **Next**. 1. If you chose to create a new deployment, choose the target core device or thing group for the deployment. On the **Specify target** page, under **Deployment target**, choose a core device or thing group, and then choose **Next**. 1. On the **Select components** page, under **Public components**, select **aws.greengrass.crypto.Pkcs11Provider**, and then choose **Next**. 1. On the **Configure components** page, select **aws.greengrass.crypto.Pkcs11Provider**, and then do the following: 1. Choose **Configure component**. 1. In the **Configure aws.greengrass.crypto.Pkcs11Provider** modal, under **Configuration update**, in **Configuration to merge**, enter the following configuration update. Update the following configuration parameters with values for the target core devices. Specify the slot ID and user PIN where you initialized the PKCS\$111 token earlier. You import the private key and certificate into this slot in the HSM later. `name` A name for the PKCS\$111 configuration. `library` The absolute file path to the PKCS\$111 implementation's library that the AWS IoT Greengrass Core software can load with libdl. `slot` The ID of the slot that contains the private key and device certificate. This value is different than the slot index or slot label. `userPin` The user PIN to use to access the slot. ``` { "name": "softhsm_pkcs11", "library": "/usr/lib/softhsm/libsofthsm2.so", "slot": 1, "userPin": "1234" } ``` 1. Choose **Confirm** to close the modal, and then choose **Next**. 1. On the **Configure advanced settings** page, keep the default configuration settings, and choose **Next**. 1. On the **Review** page, choose **Deploy**. The deployment can take up to a minute to complete. #### To deploy the PKCS\$111 provider component (AWS CLI) To deploy the PKCS\$111 provider component, create a deployment document that includes `aws.greengrass.crypto.Pkcs11Provider` in the `components` object, and specify the configuration update for the component. Follow instructions in [Create deployments](create-deployments.md) to create a new deployment or revise an existing deployment. The following example partial deployment document specifies to deploy and configure the PKCS\$111 provider component. Update the following configuration parameters with values for the target core devices. Save the slot ID and user PIN to use later when you import the private key and certificate into the HSM. `name` A name for the PKCS\$111 configuration. `library` The absolute file path to the PKCS\$111 implementation's library that the AWS IoT Greengrass Core software can load with libdl. `slot` The ID of the slot that contains the private key and device certificate. This value is different than the slot index or slot label. `userPin` The user PIN to use to access the slot. ``` { "name": "softhsm_pkcs11", "library": "/usr/lib/softhsm/libsofthsm2.so", "slot": 1, "userPin": "1234" } ``` ``` { ..., "components": { ..., "aws.greengrass.crypto.Pkcs11Provider": { "componentVersion": "2.0.0", "configurationUpdate": { "merge": "{\"name\":\"softhsm_pkcs11\",\"library\":\"/usr/lib/softhsm/libsofthsm2.so\",\"slot\":1,\"userPin\":\"1234\"}" } } } } ``` The deployment can take several minutes to complete. You can use the AWS IoT Greengrass service to check the status of the deployment. You can check the AWS IoT Greengrass Core software logs to verify that the PKCS\$111 provider component deploys successfully. For more information, see the following: + [Check deployment status](check-deployment-status.md) + [Monitor AWS IoT Greengrass logs](monitor-logs.md) If the deployment fails, you can troubleshoot the deployment on each core device. For more information, see [Troubleshooting AWS IoT Greengrass V2](troubleshooting.md). ### Step 3: Update the configuration on the core device The AWS IoT Greengrass Core software uses a configuration file that specifies how the device operates. This configuration file includes where to find the private key and certificate that the device uses to connect to the AWS Cloud. Complete the following steps to import the core device's private key and certificate into the HSM and update the configuration file to use the HSM. **To update the configuration on the core device to use hardware security** 1. Stop the AWS IoT Greengrass Core software. If you [configured the AWS IoT Greengrass Core software as a system service](configure-greengrass-core-v2.md#configure-system-service) with systemd, you can run the following command to stop the software. ``` sudo systemctl stop greengrass.service ``` 1. Find the core device's private key and certificate files. + If you installed the AWS IoT Greengrass Core software with [automatic provisioning](quick-installation.md) or [fleet provisioning](fleet-provisioning.md), the private key exists at `/greengrass/v2/privKey.key`, and the certificate exists at `/greengrass/v2/thingCert.crt`. + If you installed the AWS IoT Greengrass Core software with [manual provisioning](manual-installation.md), the private key exists at `/greengrass/v2/private.pem.key` by default, and the certificate exists at `/greengrass/v2/device.pem.crt` by default. You can also check the `system.privateKeyPath` and `system.certificateFilePath` properties in `/greengrass/v2/config/effectiveConfig.yaml` to find the location of these files. 1. Import the private key and certificate into the HSM. Check the documentation for your HSM to learn how to import private keys and certificates into it. Import the private key and certificate using the slot ID and user PIN where you initialized the PKCS\$111 token earlier. You must use the same object label and object ID for the private key and the certificate. Save the object label that you specify when you import each file. You use this label later when you update the AWS IoT Greengrass Core software configuration to use the private key and certificate in the HSM. 1. Update the AWS IoT Greengrass Core configuration to use the private key and certificate in the HSM. To update the configuration, you modify the AWS IoT Greengrass Core configuration file and run the AWS IoT Greengrass Core software with the updated configuration file to apply the new configuration. Do the following: 1. Create a back up of the AWS IoT Greengrass Core configuration file. You can use this back up to restore the core device if you run into issues when you configure hardware security. ``` sudo cp /greengrass/v2/config/effectiveConfig.yaml ~/ggc-config-backup.yaml ``` 1. Open the AWS IoT Greengrass Core configuration file in a text editor. For example, you can run the following command to use GNU nano to edit the file. Replace `/greengrass/v2` with the path to the Greengrass root folder. ``` sudo nano /greengrass/v2/config/effectiveConfig.yaml ``` 1. Replace the value of the `system.privateKeyPath` with the PKCS\$111 URI for the private key in the HSM. Replace *iotdevicekey* with the object label where you imported the private key and certificate earlier. ``` pkcs11:object=iotdevicekey;type=private ``` 1. Replace the value of the `system.certificateFilePath` with the PKCS\$111 URI for the certificate in the HSM. Replace *iotdevicekey* with the object label where you imported the private key and certificate earlier. ``` pkcs11:object=iotdevicekey;type=cert ``` After you finish these steps, the `system` property in the AWS IoT Greengrass Core configuration file should look similar to the following example. ``` system: certificateFilePath: "pkcs11:object=iotdevicekey;type=cert" privateKeyPath: "pkcs11:object=iotdevicekey;type=private" rootCaPath: "/greengrass/v2/rootCA.pem" rootpath: "/greengrass/v2" thingName: "MyGreengrassCore" ``` 1. Apply the configuration in the updated `effectiveConfig.yaml` file. Run `Greengrass.jar` with the `--init-config` parameter to apply the configuration in `effectiveConfig.yaml`. Replace `/greengrass/v2` with the path to the Greengrass root folder. ``` sudo java -Droot="/greengrass/v2" \ -jar /greengrass/v2/alts/current/distro/lib/Greengrass.jar \ --start false \ --init-config /greengrass/v2/config/effectiveConfig.yaml ``` 1. Start the AWS IoT Greengrass Core software. If you [configured the AWS IoT Greengrass Core software as a system service](configure-greengrass-core-v2.md#configure-system-service) with systemd, you can run the following command to start the software. ``` sudo systemctl start greengrass.service ``` For more information, see [Run the AWS IoT Greengrass Core software](run-greengrass-core-v2.md). 1. Check the AWS IoT Greengrass Core software logs to verify that the software starts and connects to the AWS Cloud. The AWS IoT Greengrass Core software uses the private key and certificate to connect to the AWS IoT and AWS IoT Greengrass services. ``` sudo tail -f /greengrass/v2/logs/greengrass.log ``` The following INFO-level log messages indicate that the AWS IoT Greengrass Core software successfully connects to the AWS IoT and AWS IoT Greengrass services. ``` 2021-12-06T22:47:53.702Z [INFO] (Thread-3) com.aws.greengrass.mqttclient.AwsIotMqttClient: Successfully connected to AWS IoT Core. {clientId=MyGreengrassCore5, sessionPresent=false} ``` 1. (Optional) After you verify that the AWS IoT Greengrass Core software works with the private key and certificate in the HSM, delete the private key and certificate files from the device's file system. Run the following command, and replace the file paths with the paths to the private key and certificate files. ``` sudo rm /greengrass/v2/privKey.key sudo rm /greengrass/v2/thingCert.crt ``` ## Use hardware without PKCS\$111 support The PKCS\$111 library is typically provided by the hardware vendor or is open source. For example, with standards-compliant hardware (such as TPM1.2), it might be possible to use existing open source software. However, if your hardware doesn't have a corresponding PKCS\$111 library implementation, or if you want to write a custom PKCS\$111 provider, contact your Amazon Web Services Enterprise Support representative with integration-related questions. ## See also + [PKCS \$111 Cryptographic Token Interface Usage Guide Version 2.4.0](http://docs.oasis-open.org/pkcs11/pkcs11-ug/v2.40/pkcs11-ug-v2.40.html) + [RFC 7512](https://tools.ietf.org/html/rfc7512) + [PKCS \$11: RSA Encryption Version 1.5](https://tools.ietf.org/html/rfc2313) # Device authentication and authorization for AWS IoT Greengrass Devices in AWS IoT Greengrass environments use X.509 certificates for authentication and AWS IoT policies for authorization. Certificates and policies allow devices to securely connect with each other, AWS IoT Core, and AWS IoT Greengrass. X.509 certificates are digital certificates that use the X.509 public key infrastructure standard to associate a public key with the identity contained in a certificate. X.509 certificates are issued by a trusted entity called a certificate authority (CA). The CA maintains one or more special certificates called CA certificates that it uses to issue X.509 certificates. Only the certificate authority has access to CA certificates. AWS IoT policies define the set of operations allowed for AWS IoT devices. Specifically, they allow and deny access to AWS IoT Core and AWS IoT Greengrass data plane operations, such as publishing MQTT messages and retrieving device shadows. All devices require an entry in the AWS IoT Core registry and an activated X.509 certificate with an attached AWS IoT policy. Devices fall into two categories: + **Greengrass core devices** Greengrass core devices use certificates and AWS IoT policies to connect to AWS IoT Core and AWS IoT Greengrass. The certificates and policies also allow AWS IoT Greengrass to deploy components and configurations to core devices. + **Client devices** MQTT client devices use certificates and policies to connect to AWS IoT Core and the AWS IoT Greengrass service. This enables client devices to use the AWS IoT Greengrass cloud discovery to find and connect to a Greengrass core device. A client device uses the same certificate to connect to the AWS IoT Core cloud service and core devices. Client devices also use discovery information for mutual authentication with the core device. For more information, see [Interact with local IoT devices](interact-with-local-iot-devices.md). ## X.509 certificates Communication between core devices and client devices and between devices and AWS IoT Core or AWS IoT Greengrass must be authenticated. This mutual authentication is based on registered X.509 device certificates and cryptographic keys. In an AWS IoT Greengrass environment, devices use certificates with public and private keys for the following Transport Layer Security (TLS) connections: + The AWS IoT client component on the Greengrass core device that connects to AWS IoT Core and AWS IoT Greengrass over the internet. + Client devices that connect to AWS IoT Greengrass over the internet to discover core devices. + The MQTT broker component on the Greengrass core connecting to Greengrass devices in the group over the local network. AWS IoT Greengrass core devices store certificates in the Greengrass root folder. ### Certificate authority (CA) certificates Greengrass core devices and client devices download a root CA certificate used for authentication with the AWS IoT Core and AWS IoT Greengrass services. We recommend that you use an Amazon Trust Services (ATS) root CA certificate, such as [Amazon Root CA 1](https://www.amazontrust.com/repository/AmazonRootCA1.pem). For more information, see [CA certificates for server authentication](https://docs.aws.amazon.com/iot/latest/developerguide/server-authentication.html#server-authentication-certs) in the *AWS IoT Core Developer Guide*. Client devices also download a Greengrass core device CA certificate. They use this certificate to validate the MQTT server certificate on the core device during mutual authentication. ### Certificate rotation on the local MQTT broker When you [enable client device support](interact-with-local-iot-devices.md), Greengrass core devices generate a local MQTT server certificate that client devices use for mutual authentication. This certificate is signed by the core device CA certificate, which the core device stores in the AWS IoT Greengrass cloud. Client devices retrieve the core device CA certificate when they discover the core device. They use the core device CA certificate to verify the core device's MQTT server certificate when they connect to the core device. The core device CA certificate expires after 5 years. The MQTT server certificate expires every 7 days by default, and you can configure this duration to between 2 and 10 days. This limited period is based on security best practices. This rotation helps mitigate the threat of an attacker stealing the MQTT server certificate and private key to impersonate the Greengrass core device. The Greengrass core device rotates the MQTT server certificate 24 hours before it expires. The Greengrass core device generates a new certificate and restarts the local MQTT broker. When this happens, all client devices connected to the Greengrass core device are disconnected. Client devices can reconnect to the Greengrass core device after a short period of time. ## AWS IoT policies for data plane operations Use AWS IoT policies to authorize access to the AWS IoT Core and AWS IoT Greengrass data planes. The AWS IoT Core data plane provides operations for devices, users, and applications. These operations include the ability to connect to AWS IoT Core and subscribe to topics. The AWS IoT Greengrass data plane provides operations for Greengrass devices. For more information, see [AWS IoT Greengrass V2 policy actions](#greengrass-policy-actions). These operations include the ability to resolve component dependencies and download public component artifacts. An AWS IoT policy is a JSON document that's similar to an [IAM policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_grammar.html#policies-grammar-json). It contains one or more policy statements that specify the following properties: + `Effect`. The access mode, which can be `Allow` or `Deny`. + `Action`. The list of actions that are allowed or denied by the policy. + `Resource`. The list of resources on which the action is allowed or denied. AWS IoT policies support `*` as a wildcard character, and treat MQTT wildcard characters (`+` and `#`) as literal strings. For more information about the `*` wildcard, see [Using wildcard in resource ARNs](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_resource.html#reference_policies_elements_resource_wildcards) in the *AWS Identity and Access Management User Guide*. For more information, see [AWS IoT policies](https://docs.aws.amazon.com/iot/latest/developerguide/iot-policies.html) and [AWS IoT policy actions](https://docs.aws.amazon.com/iot/latest/developerguide/iot-policy-actions.html) in the *AWS IoT Core Developer Guide*. **Important** [Thing policy variables](https://docs.aws.amazon.com/iot/latest/developerguide/thing-policy-variables.html) (`iot:Connection.Thing.*`) aren't supported for in AWS IoT policies for core devices or Greengrass data plane operations. Instead, you can use a wildcard that matches multiple devices that have similar names. For example, you can specify `MyGreengrassDevice*` to match `MyGreengrassDevice1`, `MyGreengrassDevice2`, and so on. **Note** AWS IoT Core enables you to attach AWS IoT policies to thing groups to define permissions for groups of devices. Thing group policies don't allow access to AWS IoT Greengrass data plane operations. To allow a thing access to an AWS IoT Greengrass data plane operation, add the permission to an AWS IoT policy that you attach to the thing's certificate. ### AWS IoT Greengrass V2 policy actions AWS IoT Greengrass V2 defines the following policy actions that Greengrass core devices and client devices can use in AWS IoT policies. To specify a resource for an policy action, you use the Amazon Resource Name (ARN) of the resource.Core device actions `greengrass:GetComponentVersionArtifact` Grants permission to get a presigned URL to download a public component artifact or a Lambda component artifact. This permission is evaluated when a core device receives a deployment that specifies a public component or a Lambda that has artifacts. If the core device already has the artifact, it doesn't download the artifact again. Resource type: `componentVersion` Resource ARN format: `arn:aws:greengrass:region:account-id:components:component-name:versions:component-version` `greengrass:ResolveComponentCandidates` Grants permission to identify a list of components that meet the component, version, and platform requirements for a deployment. If the requirements conflict, or no components exist that meet the requirements, this operation returns an error and the deployment fails on the device. This permission is evaluated when a core device receives a deployment that specifies components. Resource type: None Resource ARN format: `*` `greengrass:GetDeploymentConfiguration` Grants permission to get a presigned URL to download a large deployment document. This permission is evaluated when a core device receives a deployment that specifies a deployment document larger than 7 KB (if the deployment targets a thing) or 31 KB (if the deployment targets a thing group). The deployment document includes component configurations, deployment policies, and deployment metadata. For more information, see [Deploy AWS IoT Greengrass components to devices](manage-deployments.md). This feature is available for v2.3.0 and later of the [Greengrass nucleus component](greengrass-nucleus-component.md). Resource type: None Resource ARN format: `*` `greengrass:ListThingGroupsForCoreDevice` Grants permission to get a core device's thing group hierarchy. This permission is checked when a core device receives a deployment from AWS IoT Greengrass. The core device uses this action to identify whether it was removed from a thing group since the last deployment. If the core device was removed from a thing group, and that thing group is the target of a deployment to the core device, then the core device removes the components installed by that deployment. This feature is used by v2.5.0 and later of the [Greengrass nucleus component](greengrass-nucleus-component.md). Resource type: `thing` (core device) Resource ARN format: `arn:aws:iot:region:account-id:thing/core-device-thing-name` `greengrass:VerifyClientDeviceIdentity` Grants permission to verify the identity of a client device that connects to a core device. This permission is evaluated when a core device runs the [client device auth component](client-device-auth-component.md) and receives an MQTT connection from a client device. The client device presents its AWS IoT device certificate. Then, the core device sends the device certificate to the AWS IoT Greengrass cloud service to verify the client device's identity. For more information, see [Interact with local IoT devices](interact-with-local-iot-devices.md). Resource type: None Resource ARN format: `*` `greengrass:VerifyClientDeviceIoTCertificateAssociation` Grants permission to verify whether a client device is associated with an AWS IoT certificate. This permission is evaluated when a core device runs the [client device auth component](client-device-auth-component.md) and authorizes a client device to connect over MQTT. For more information, see [Interact with local IoT devices](interact-with-local-iot-devices.md). For a core device to use this operation, the [Greengrass service role](greengrass-service-role.md) must be associated to your AWS account and allow the `iot:DescribeCertificate` permission. Resource type: `thing` (client device) Resource ARN format: `arn:aws:iot:region:account-id:thing/client-device-thing-name` `greengrass:PutCertificateAuthorities` Grants permission to upload certificate authority (CA) certificates that client devices can download to verify the core device. This permission is evaluated when a core device installs and runs the [client device auth component](client-device-auth-component.md). This component creates a local certificate authority and uses this operation to upload its CA certificates. Client devices download these CA certificates when they use the [Discover](#greengrass-discover-action) operation to find core devices where they can connect. When client devices connect to an MQTT broker on a core device, they use these CA certificates to verify the identity of the core device. For more information, see [Interact with local IoT devices](interact-with-local-iot-devices.md). Resource type: None ARN format: `*` `greengrass:GetConnectivityInfo` Grants permission to get connectivity information for a core device. This information describes how client devices can connect to the core device. This permission is evaluated when a core device installs and runs the [client device auth component](client-device-auth-component.md). This component uses the connectivity information to generate valid CA certificates to upload to the AWS IoT Greengrass cloud service with the [PutCertificateAuthories](#greengrass-put-certificate-authorities-action) operation. Client devices use these CA certificates to verify the identity of the core device. For more information, see [Interact with local IoT devices](interact-with-local-iot-devices.md). You can also use this operation on the AWS IoT Greengrass control plane to view connectivity information for a core device. For more information, see [GetConnectivityInfo](https://docs.aws.amazon.com/greengrass/v1/apireference/getconnectivityinfo-get.html) in the *AWS IoT Greengrass V1 API Reference*. Resource type: `thing` (core device) Resource ARN format: `arn:aws:iot:region:account-id:thing/core-device-thing-name` `greengrass:UpdateConnectivityInfo` Grants permission to update connectivity information for a core device. This information describes how client devices can connect to the core device. This permission is evaluated when a core device runs the [IP detector component](ip-detector-component.md). This component identifies the information that client devices require to connect to the core device on the local network. Then, this component uses this operation to upload the connectivity information to the AWS IoT Greengrass cloud service, so client devices can retrieve this information with the [Discover](#greengrass-discover-action) operation. For more information, see [Interact with local IoT devices](interact-with-local-iot-devices.md). You can also use this operation on the AWS IoT Greengrass control plane to manually update connectivity information for a core device. For more information, see [UpdateConnectivityInfo](https://docs.aws.amazon.com/greengrass/v1/apireference/updateconnectivityinfo-put.html) in the *AWS IoT Greengrass V1 API Reference*. Resource type: `thing` (core device) Resource ARN format: `arn:aws:iot:region:account-id:thing/core-device-thing-name`Client device actions `greengrass:Discover` Grants permission to discover connectivity information for core devices where a client device can connect. This information describes how the client device can connect to the core devices. A client device can discover only the core devices that you have associated it with by using the [BatchAssociateClientDeviceWithCoreDevice](https://docs.aws.amazon.com/greengrass/v2/APIReference/API_BatchAssociateClientDeviceWithCoreDevice.html) operation. For more information, see [Interact with local IoT devices](interact-with-local-iot-devices.md). Resource type: `thing` (client device) Resource ARN format: `arn:aws:iot:region:account-id:thing/client-device-thing-name` ## Update a core device's AWS IoT policy You can use the AWS IoT Greengrass and AWS IoT consoles or the AWS IoT API to view and update a core device's AWS IoT policy. **Note** If you used the [AWS IoT Greengrass Core software installer to provision resources](quick-installation.md), your core device has an AWS IoT policy that allows access to all AWS IoT Greengrass actions (`greengrass:*`). You can follow these steps to restrict access to only the actions that a core device uses. ### Review and update a core device's AWS IoT policy (console) 1. In the [AWS IoT Greengrass console](https://console.aws.amazon.com/greengrass) navigation menu, choose **Core devices**. 1. On the **Core devices** page, choose the core device to update. 1. On the core device details page, choose the link to the core device's **Thing**. This link opens the thing details page in the AWS IoT console. 1. On the thing details page, choose **Certificates**. 1. In the **Certificates** tab, choose the thing's active certificate. 1. On the certificate details page, choose **Policies**. 1. In the **Policies** tab, choose the AWS IoT policy to review and update. You can add the required permissions to any policy that is attached to the core device's active certificate. **Note** If you used the [AWS IoT Greengrass Core software installer to provision resources](quick-installation.md), you have two AWS IoT policies. We recommend that you choose the policy named **GreengrassV2IoTThingPolicy**, if it exists. Core devices that you create with the quick installer use this policy name by default. If you add permissions to this policy, you are also granting these permissions to other core devices that use this policy. 1. In the policy overview, choose **Edit active version**. 1. Review the policy and add, remove, or edit permissions as needed. 1. To set a new policy version as the active version, under **Policy version status**, select **Set the edited version as the active version for this policy**. 1. Choose **Save as new version**. ### Review and update a core device's AWS IoT policy (AWS CLI) 1. List the principals for the core device's AWS IoT thing. Thing principals can be X.509 device certificates or other identifies. Run the following command, and replace *MyGreengrassCore* with the name of the core device. ``` aws iot list-thing-principals --thing-name MyGreengrassCore ``` The operation returns a response that lists the core device's thing principals. ``` { "principals": [ "arn:aws:iot:us-west-2:123456789012:cert/certificateId" ] } ``` 1. Identify the core device's active certificate. Run the following command, and replace *certificateId* with the ID of each certificate from the previous step until you find the active certificate. The certificate ID is the hexadecimal string at the end of the certificate ARN. The `--query` argument specifies to output only the certificate's status. ``` aws iot describe-certificate --certificate-id certificateId --query 'certificateDescription.status' ``` The operation returns the certificate status as a string. For example, if the certificate is active, this operation outputs `"ACTIVE"`. 1. List the AWS IoT policies that are attached to the certificate. Run the following command, and replace the certificate ARN with the ARN of the certificate. ``` aws iot list-principal-policies --principal arn:aws:iot:us-west-2:123456789012:cert/certificateId ``` The operation returns a response that lists the AWS IoT policies that are attached to the certificate. ``` { "policies": [ { "policyName": "GreengrassTESCertificatePolicyMyGreengrassCoreTokenExchangeRoleAlias", "policyArn": "arn:aws:iot:us-west-2:123456789012:policy/GreengrassTESCertificatePolicyMyGreengrassCoreTokenExchangeRoleAlias" }, { "policyName": "GreengrassV2IoTThingPolicy", "policyArn": "arn:aws:iot:us-west-2:123456789012:policy/GreengrassV2IoTThingPolicy" } ] } ``` 1. Choose the policy to view and update. **Note** If you used the [AWS IoT Greengrass Core software installer to provision resources](quick-installation.md), you have two AWS IoT policies. We recommend that you choose the policy named **GreengrassV2IoTThingPolicy**, if it exists. Core devices that you create with the quick installer use this policy name by default. If you add permissions to this policy, you are also granting these permissions to other core devices that use this policy. 1. Get the policy's document. Run the following command, and replace *GreengrassV2IoTThingPolicy* with the name of the policy. ``` aws iot get-policy --policy-name GreengrassV2IoTThingPolicy ``` The operation returns a response that contains the policy's document and other information about the policy. The policy document is a JSON object serialized as a string. ``` { "policyName": "GreengrassV2IoTThingPolicy", "policyArn": "arn:aws:iot:us-west-2:123456789012:policy/GreengrassV2IoTThingPolicy", "policyDocument": "{\ \\"Version\\": \\"2012-10-17 \\",\ \\"Statement\\": [\ {\ \\"Effect\\": \\"Allow\\",\ \\"Action\\": [\ \\"iot:Connect\\",\ \\"iot:Publish\\",\ \\"iot:Subscribe\\",\ \\"iot:Receive\\",\ \\"greengrass:*\\"\ ],\ \\"Resource\\": \\"*\\"\ }\ ]\ }", "defaultVersionId": "1", "creationDate": "2021-02-05T16:03:14.098000-08:00", "lastModifiedDate": "2021-02-05T16:03:14.098000-08:00", "generationId": "f19144b798534f52c619d44f771a354f1b957dfa2b850625d9f1d0fde530e75f" } ``` 1. Use an online converter or other tool to convert the policy document string to a JSON object, and then save it to a file named `iot-policy.json`. For example, if you have the [jq](https://stedolan.github.io/jq/) tool installed, you can run the following command to get the policy document, convert it to a JSON object, and save the policy document as a JSON object. ``` aws iot get-policy --policy-name GreengrassV2IoTThingPolicy --query 'policyDocument' | jq fromjson >> iot-policy.json ``` 1. Review the policy document, and add, remove, or edit permissions as needed. For example, on a Linux-based system, you can run the following command to use GNU nano to open the file. ``` nano iot-policy.json ``` When you're done, the policy document might look similar to the [minimal AWS IoT policy for core devices](#greengrass-core-minimal-iot-policy). 1. Save the changes as a new version of the policy. Run the following command, and replace *GreengrassV2IoTThingPolicy* with the name of the policy. ``` aws iot create-policy-version --policy-name GreengrassV2IoTThingPolicy --policy-document file://iot-policy.json --set-as-default ``` The operation returns a response similar to the following example if it succeeds. ``` { "policyArn": "arn:aws:iot:us-west-2:123456789012:policy/GreengrassV2IoTThingPolicy", "policyDocument": "{\ \\"Version\\": \\"2012-10-17 \\",\ \\"Statement\\": [\ {\ \\"Effect\\": \\"Allow\\",\ \\"Action\\": [\ \\t\\t\\"iot:Connect\\",\ \\t\\t\\"iot:Publish\\",\ \\t\\t\\"iot:Subscribe\\",\ \\t\\t\\"iot:Receive\\",\ \\t\\t\\"greengrass:*\\"\ ],\ \\"Resource\\": \\"*\\"\ }\ ]\ }", "policyVersionId": "2", "isDefaultVersion": true } ``` ## Minimal AWS IoT policy for AWS IoT Greengrass V2 core devices **Important** Later versions of the [Greengrass nucleus component](greengrass-nucleus-component.md) require additional permissions on the minimal AWS IoT policy. You might need to [update your core devices' AWS IoT policies](#update-core-device-iot-policy) to grant additional permissions. Core devices that run Greengrass nucleus v2.5.0 and later use the `greengrass:ListThingGroupsForCoreDevice` permission to uninstall components when you remove a core device from a thing group. Core devices that run Greengrass nucleus v2.3.0 and later use the `greengrass:GetDeploymentConfiguration` permission to support large deployment configuration documents. The following example policy includes the minimum set of actions required to support basic Greengrass functionality for your core device. + The `Connect` policy includes the `*` wildcard after the core device thing name (for example, `core-device-thing-name*`). The core device uses the same device certificate to make multiple concurrent subscriptions to AWS IoT Core, but the client ID in a connection might not be an exact match of the core device thing name. After the first 50 subscriptions, the core device uses `core-device-thing-name#number` as the client ID, where `number` increments for each additional 50 subscriptions. For example, when a core device named `MyCoreDevice` creates 150 concurrent subscriptions, it uses the following client IDs: + Subscriptions 1 to 50: `MyCoreDevice` + Subscriptions 51 to 100: `MyCoreDevice#2` + Subscriptions 101 to 150: `MyCoreDevice#3` The wildcard allows the core device to connect when it uses these client IDs that have a suffix. + The policy lists the MQTT topics and topic filters that the core device can publish messages to, subscribe to, and receive messages on, including topics used for shadow state. To support message exchange between AWS IoT Core, Greengrass components, and client devices, specify the topics and topic filters that you want to allow. For more information, see [Publish/Subscribe policy examples](https://docs.aws.amazon.com/iot/latest/developerguide/pub-sub-policy.html) in the *AWS IoT Core Developer Guide*. + The policy grants permission to publish to the following topic for telemetry data. ``` $aws/things/core-device-thing-name/greengrass/health/json ``` You can remove this permission for core devices where you disable telemetry. For more information, see [Gather system health telemetry data from AWS IoT Greengrass core devices](telemetry.md). + The policy grants permission to assume an IAM role through an AWS IoT role alias. The core device uses this role, called the token exchange role, to acquire AWS credentials that it can use to authenticate AWS requests. For more information, see [Authorize core devices to interact with AWS services](device-service-role.md). When you install the AWS IoT Greengrass Core software, you create and attach a second AWS IoT policy that includes only this permission. If you include this permission in your core device's primary AWS IoT policy, you can detach and delete the other AWS IoT policy. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Connect" ], "Resource": "arn:aws:iot:us-east-1:123456789012:client/core-device-thing-name*" }, { "Effect": "Allow", "Action": [ "iot:Receive", "iot:Publish" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/core-device-thing-name/greengrass/health/json", "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/core-device-thing-name/greengrassv2/health/json", "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/core-device-thing-name/jobs/*", "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/core-device-thing-name/shadow/*" ] }, { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/core-device-thing-name/jobs/*", "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/core-device-thing-name/shadow/*" ] }, { "Effect": "Allow", "Action": "iot:AssumeRoleWithCertificate", "Resource": "arn:aws:iot:us-east-1:123456789012:rolealias/token-exchange-role-alias-name" }, { "Effect": "Allow", "Action": [ "greengrass:GetComponentVersionArtifact", "greengrass:ResolveComponentCandidates", "greengrass:GetDeploymentConfiguration", "greengrass:ListThingGroupsForCoreDevice" ], "Resource": "*" } ] } ``` ------ ## Minimal AWS IoT policy to support client devices The following example policy includes the minimum set of actions required to support interaction with client devices on a core device. To support client devices, a core device must have the permissions in this AWS IoT policy in addition to the [Minimal AWS IoT policy for basic operation](#greengrass-core-minimal-iot-policy). + The policy allows the core device to update its own connectivity information. This permission (`greengrass:UpdateConnectivityInfo`) is required only if you deploy the [IP detector component](ip-detector-component.md) to the core device. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Publish" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/core-device-thing-name-gci/shadow/get" ] }, { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/core-device-thing-name-gci/shadow/update/delta", "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/core-device-thing-name-gci/shadow/get/accepted" ] }, { "Effect": "Allow", "Action": [ "iot:Receive" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/core-device-thing-name-gci/shadow/update/delta", "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/core-device-thing-name-gci/shadow/get/accepted" ] }, { "Effect": "Allow", "Action": [ "greengrass:PutCertificateAuthorities", "greengrass:VerifyClientDeviceIdentity" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "greengrass:VerifyClientDeviceIoTCertificateAssociation" ], "Resource": "arn:aws:iot:us-east-1:123456789012:thing/*" }, { "Effect": "Allow", "Action": [ "greengrass:GetConnectivityInfo", "greengrass:UpdateConnectivityInfo" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:thing/core-device-thing-name" ] } ] } ``` ------ ## Minimal AWS IoT policy for client devices The following example policy includes the minimum set of actions required for a client device to discover core devices where they connect and communicate over MQTT. The client device's AWS IoT policy must include the `greengrass:Discover` action to allow the device to discover connectivity information for its associated Greengrass core devices. In the `Resource` section, specify the Amazon Resource Name (ARN) of the client device, not the ARN of the Greengrass core device. + The policy allows communication on all MQTT topics. To follow best security practices, restrict the `iot:Publish`, `iot:Subscribe`, and `iot:Receive` permissions to the minimal set of topics that a client device requires for your use case. + The policy allows the thing to discover core devices for all AWS IoT things. To follow best security practices, restrict the `greengrass:Discover` permission to the client device's AWS IoT thing or a wildcard that matches a set of AWS IoT things. **Important** [Thing policy variables](https://docs.aws.amazon.com/iot/latest/developerguide/thing-policy-variables.html) (`iot:Connection.Thing.*`) aren't supported for in AWS IoT policies for core devices or Greengrass data plane operations. Instead, you can use a wildcard that matches multiple devices that have similar names. For example, you can specify `MyGreengrassDevice*` to match `MyGreengrassDevice1`, `MyGreengrassDevice2`, and so on. + A client device's AWS IoT policy doesn't typically require permissions for `iot:GetThingShadow`, `iot:UpdateThingShadow`, or `iot:DeleteThingShadow` actions, because the Greengrass core device handles shadow sync operations for client devices. To enable the core device to handle client device shadows, check that the core device's AWS IoT policy allows these actions, and that the `Resource` section includes the ARNs of the client devices. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:Connect" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "iot:Publish" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/*" ] }, { "Effect": "Allow", "Action": [ "iot:Subscribe" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topicfilter/*" ] }, { "Effect": "Allow", "Action": [ "iot:Receive" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:topic/*" ] }, { "Effect": "Allow", "Action": [ "greengrass:Discover" ], "Resource": [ "arn:aws:iot:us-east-1:123456789012:thing/*" ] } ] } ``` ------ # Identity and access management for AWS IoT Greengrass AWS Identity and Access Management (IAM) is an AWS service that helps an administrator securely control access to AWS resources. IAM administrators control who can be *authenticated* (signed in) and *authorized* (have permissions) to use AWS IoT Greengrass resources. IAM is an AWS service that you can use with no additional charge. **Note** This topic describes IAM concepts and features. For information about IAM features supported by AWS IoT Greengrass, see [How AWS IoT Greengrass works with IAM](security_iam_service-with-iam.md). ## Audience How you use AWS Identity and Access Management (IAM) differs based on your role: + **Service user** - request permissions from your administrator if you cannot access features (see [Troubleshooting identity and access issues for AWS IoT Greengrass](security_iam_troubleshoot.md)) + **Service administrator** - determine user access and submit permission requests (see [How AWS IoT Greengrass works with IAM](security_iam_service-with-iam.md)) + **IAM administrator** - write policies to manage access (see [Identity-based policy examples for AWS IoT Greengrass](security_iam_id-based-policy-examples.md)) ## Authenticating with identities Authentication is how you sign in to AWS using your identity credentials. You must be authenticated as the AWS account root user, an IAM user, or by assuming an IAM role. You can sign in as a federated identity using credentials from an identity source like AWS IAM Identity Center (IAM Identity Center), single sign-on authentication, or Google/Facebook credentials. For more information about signing in, see [How to sign in to your AWS account](https://docs.aws.amazon.com/signin/latest/userguide/how-to-sign-in.html) in the *AWS Sign-In User Guide*. For programmatic access, AWS provides an SDK and CLI to cryptographically sign requests. For more information, see [AWS Signature Version 4 for API requests](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) in the *IAM User Guide*. ### AWS account root user When you create an AWS account, you begin with one sign-in identity called the AWS account *root user* that has complete access to all AWS services and resources. We strongly recommend that you don't use the root user for everyday tasks. For tasks that require root user credentials, see [Tasks that require root user credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html#root-user-tasks) in the *IAM User Guide*. ### IAM users and groups An *[IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html)* is an identity with specific permissions for a single person or application. We recommend using temporary credentials instead of IAM users with long-term credentials. For more information, see [Require human users to use federation with an identity provider to access AWS using temporary credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#bp-users-federation-idp) in the *IAM User Guide*. An [https://docs.aws.amazon.com/IAM/latest/UserGuide/id_groups.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_groups.html) specifies a collection of IAM users and makes permissions easier to manage for large sets of users. For more information, see [Use cases for IAM users](https://docs.aws.amazon.com/IAM/latest/UserGuide/gs-identities-iam-users.html) in the *IAM User Guide*. ### IAM roles An *[IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html)* is an identity with specific permissions that provides temporary credentials. You can assume a role by [switching from a user to an IAM role (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-console.html) or by calling an AWS CLI or AWS API operation. For more information, see [Methods to assume a role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_manage-assume.html) in the *IAM User Guide*. IAM roles are useful for federated user access, temporary IAM user permissions, cross-account access, cross-service access, and applications running on Amazon EC2. For more information, see [Cross account resource access in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies-cross-account-resource-access.html) in the *IAM User Guide*. ## Managing access using policies You control access in AWS by creating policies and attaching them to AWS identities or resources. A policy defines permissions when associated with an identity or resource. AWS evaluates these policies when a principal makes a request. Most policies are stored in AWS as JSON documents. For more information about JSON policy documents, see [Overview of JSON policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#access_policies-json) in the *IAM User Guide*. Using policies, administrators specify who has access to what by defining which **principal** can perform **actions** on what **resources**, and under what **conditions**. By default, users and roles have no permissions. An IAM administrator creates IAM policies and adds them to roles, which users can then assume. IAM policies define permissions regardless of the method used to perform the operation. ### Identity-based policies Identity-based policies are JSON permissions policy documents that you attach to an identity (user, group, or role). These policies control what actions identities can perform, on which resources, and under what conditions. To learn how to create an identity-based policy, see [Define custom IAM permissions with customer managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) in the *IAM User Guide*. Identity-based policies can be *inline policies* (embedded directly into a single identity) or *managed policies* (standalone policies attached to multiple identities). To learn how to choose between managed and inline policies, see [Choose between managed policies and inline policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies-choosing-managed-or-inline.html) in the *IAM User Guide*. ### Resource-based policies Resource-based policies are JSON policy documents that you attach to a resource. Examples include IAM *role trust policies* and Amazon S3 *bucket policies*. In services that support resource-based policies, service administrators can use them to control access to a specific resource. You must [specify a principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html) in a resource-based policy. Resource-based policies are inline policies that are located in that service. You can't use AWS managed policies from IAM in a resource-based policy. ### Access control lists (ACLs) Access control lists (ACLs) control which principals (account members, users, or roles) have permissions to access a resource. ACLs are similar to resource-based policies, although they do not use the JSON policy document format. Amazon S3, AWS WAF, and Amazon VPC are examples of services that support ACLs. To learn more about ACLs, see [Access control list (ACL) overview](https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html) in the *Amazon Simple Storage Service Developer Guide*. ### Other policy types AWS supports additional policy types that can set the maximum permissions granted by more common policy types: + **Permissions boundaries** – Set the maximum permissions that an identity-based policy can grant to an IAM entity. For more information, see [Permissions boundaries for IAM entities](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html) in the *IAM User Guide*. + **Service control policies (SCPs)** – Specify the maximum permissions for an organization or organizational unit in AWS Organizations. For more information, see [Service control policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_scps.html) in the *AWS Organizations User Guide*. + **Resource control policies (RCPs)** – Set the maximum available permissions for resources in your accounts. For more information, see [Resource control policies (RCPs)](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_rcps.html) in the *AWS Organizations User Guide*. + **Session policies** – Advanced policies passed as a parameter when creating a temporary session for a role or federated user. For more information, see [Session policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#policies_session) in the *IAM User Guide*. ### Multiple policy types When multiple types of policies apply to a request, the resulting permissions are more complicated to understand. To learn how AWS determines whether to allow a request when multiple policy types are involved, see [Policy evaluation logic](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_evaluation-logic.html) in the *IAM User Guide*. ## See also + [How AWS IoT Greengrass works with IAM](security_iam_service-with-iam.md) + [Identity-based policy examples for AWS IoT Greengrass](security_iam_id-based-policy-examples.md) + [Troubleshooting identity and access issues for AWS IoT Greengrass](security_iam_troubleshoot.md) # How AWS IoT Greengrass works with IAM Before you use IAM to manage access to AWS IoT Greengrass, you should understand the IAM features that you can use with AWS IoT Greengrass. | IAM feature | Supported by Greengrass? | | --- | --- | | [Identity-based policies with resource-level permissions](#security_iam_service-with-iam-id-based-policies) | Yes | | [Resource-based policies](#security_iam_service-with-iam-resource-based-policies) | No | | [Access control lists (ACLs)](#security_iam_service-with-iam-acls) | No | | [Tags-based authorization](#security_iam_service-with-iam-tags) | Yes | | [Temporary credentials](#security_iam_service-with-iam-roles-tempcreds) | Yes | | [Service-linked roles](#security_iam_service-with-iam-roles-service-linked) | No | | [Service roles](#security_iam_service-with-iam-roles-service-linked) | Yes | For a high-level view of how other AWS services work with IAM, see [AWS services that work with IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-services-that-work-with-iam.html) in the *IAM User Guide*. ## Identity-based policies for AWS IoT Greengrass With IAM identity-based policies, you can specify allowed or denied actions and resources and the conditions under which actions are allowed or denied. AWS IoT Greengrass supports specific actions, resources, and condition keys. To learn about all of the elements that you use in a policy, see [IAM JSON policy elements reference](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements.html) in the *IAM User Guide*. ### Actions Administrators can use AWS JSON policies to specify who has access to what. That is, which **principal** can perform **actions** on what **resources**, and under what **conditions**. The `Action` element of a JSON policy describes the actions that you can use to allow or deny access in a policy. Include actions in a policy to grant permissions to perform the associated operation. Policy actions for AWS IoT Greengrass use the `greengrass:` prefix before the action. For example, to allow someone to use the `ListCoreDevices` API operation to list the core devices in their AWS account, you include the `greengrass:ListCoreDevices` action in their policy. Policy statements must include either an `Action` or `NotAction` element. AWS IoT Greengrass defines its own set of actions that describe tasks that you can perform with this service. To specify multiple actions in a single statement, list them between brackets (`[` `]`) and separate them with commas, as follows: ``` "Action": [ "greengrass:action1", "greengrass:action2", "greengrass:action3" ] ``` You can use wildcards (`*`) to specify multiple actions. For example, to specify all actions that begin with the word `List`, include the following action: ``` "Action": "greengrass:List*" ``` **Note** We recommend that you avoid the use of wildcards to specify all available actions for a service. As a best practice, you should grant least privilege and narrowly scope permissions in a policy. For more information, see [Grant minimum possible permissions](security-best-practices.md#least-privilege). For the complete list of AWS IoT Greengrass actions, see [Actions Defined by AWS IoT Greengrass](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_awsiotgreengrass.html#awsiotgreengrass-actions-as-permissions) in the *IAM User Guide*. ### Resources Administrators can use AWS JSON policies to specify who has access to what. That is, which **principal** can perform **actions** on what **resources**, and under what **conditions**. The `Resource` JSON policy element specifies the object or objects to which the action applies. As a best practice, specify a resource using its [Amazon Resource Name (ARN)](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html). For actions that don't support resource-level permissions, use a wildcard (\$1) to indicate that the statement applies to all resources. ``` "Resource": "*" ``` The following table contains the AWS IoT Greengrass resource ARNs that can be used in the `Resource` element of a policy statement. For a mapping of supported resource-level permissions for AWS IoT Greengrass actions, see [Actions Defined by AWS IoT Greengrass](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_awsiotgreengrass.html#awsiotgreengrass-actions-as-permissions) in the *IAM User Guide*. Some AWS IoT Greengrass actions (for example, some list operations), cannot be performed on a specific resource. In those cases, you must use the wildcard alone. ``` "Resource": "*" ``` To specify multiple resource ARNs in a statement, list them between brackets (`[` `]`) and separate them with commas, as follows: ``` "Resource": [ "resource-arn1", "resource-arn2", "resource-arn3" ] ``` For more information about ARN formats, see [Amazon Resource Names (ARNs) and AWS service namespaces](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) in the *Amazon Web Services General Reference*. ### Condition keys Administrators can use AWS JSON policies to specify who has access to what. That is, which **principal** can perform **actions** on what **resources**, and under what **conditions**. The `Condition` element specifies when statements execute based on defined criteria. You can create conditional expressions that use [condition operators](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition_operators.html), such as equals or less than, to match the condition in the policy with values in the request. To see all AWS global condition keys, see [AWS global condition context keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html) in the *IAM User Guide*. ### Examples To view examples of AWS IoT Greengrass identity-based policies, see [Identity-based policy examples for AWS IoT Greengrass](security_iam_id-based-policy-examples.md). ## Resource-based policies for AWS IoT Greengrass AWS IoT Greengrass does not support [resource-based policies](security-iam.md#security_iam_access-manage-resource-based-policies). ## Access control lists (ACLs) AWS IoT Greengrass does not support [ACLs](security-iam.md#security_iam_access-manage-acl). ## Authorization based on AWS IoT Greengrass tags You can attach tags to supported AWS IoT Greengrass resources or pass tags in a request to AWS IoT Greengrass. To control access based on tags, you provide tag information in the [Condition element](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition.html) of a policy using the `aws:ResourceTag/${TagKey}`, `aws:RequestTag/${TagKey}`, or `aws:TagKeys` condition keys. For more information, see [Tag your AWS IoT Greengrass Version 2 resources](tag-resources.md). ## IAM roles for AWS IoT Greengrass An [IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) is an entity within your AWS account that has specific permissions. ### Using temporary credentials with AWS IoT Greengrass Temporary credentials are used to sign in with federation, assume an IAM role, or to assume a cross-account role. You obtain temporary security credentials by calling AWS STS API operations such as [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) or [GetFederationToken](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetFederationToken.html). On the Greengrass core, temporary credentials for the [device role](device-service-role.md) are made available to Greengrass components. If your components use the AWS SDK, you don't need to add logic to obtain the credentials because the AWS SDK does this for you. ### Service-linked roles AWS IoT Greengrass does not support [service-linked roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-service-linked-role). ### Service roles This feature allows a service to assume a [service role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-service-role) on your behalf. This role allows the service to access resources in other services to complete an action on your behalf. Service roles appear in your IAM account and are owned by the account. This means that an IAM administrator can change the permissions for this role. However, doing so might break the functionality of the service. AWS IoT Greengrass core devices use a service role to allow Greengrass components and Lambda functions to access some of your AWS resources on your behalf. For more information, see [Authorize core devices to interact with AWS services](device-service-role.md). AWS IoT Greengrass uses a service role to access some of your AWS resources on your behalf. For more information, see [Greengrass service role](greengrass-service-role.md). # Identity-based policy examples for AWS IoT Greengrass By default, IAM users and roles don't have permission to create or modify AWS IoT Greengrass resources. They also can't perform tasks using the AWS Management Console, AWS CLI, or AWS API. An IAM administrator must create IAM policies that grant users and roles permission to perform specific API operations on the specified resources they need. The administrator must then attach those policies to the IAM users or groups that require those permissions. ## Policy best practices Identity-based policies determine whether someone can create, access, or delete AWS IoT Greengrass resources in your account. These actions can incur costs for your AWS account. When you create or edit identity-based policies, follow these guidelines and recommendations: + **Get started with AWS managed policies and move toward least-privilege permissions** – To get started granting permissions to your users and workloads, use the *AWS managed policies* that grant permissions for many common use cases. They are available in your AWS account. We recommend that you reduce permissions further by defining AWS customer managed policies that are specific to your use cases. For more information, see [AWS managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#aws-managed-policies) or [AWS managed policies for job functions](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_job-functions.html) in the *IAM User Guide*. + **Apply least-privilege permissions** – When you set permissions with IAM policies, grant only the permissions required to perform a task. You do this by defining the actions that can be taken on specific resources under specific conditions, also known as *least-privilege permissions*. For more information about using IAM to apply permissions, see [ Policies and permissions in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) in the *IAM User Guide*. + **Use conditions in IAM policies to further restrict access** – You can add a condition to your policies to limit access to actions and resources. For example, you can write a policy condition to specify that all requests must be sent using SSL. You can also use conditions to grant access to service actions if they are used through a specific AWS service, such as CloudFormation. For more information, see [ IAM JSON policy elements: Condition](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_condition.html) in the *IAM User Guide*. + **Use IAM Access Analyzer to validate your IAM policies to ensure secure and functional permissions** – IAM Access Analyzer validates new and existing policies so that the policies adhere to the IAM policy language (JSON) and IAM best practices. IAM Access Analyzer provides more than 100 policy checks and actionable recommendations to help you author secure and functional policies. For more information, see [Validate policies with IAM Access Analyzer](https://docs.aws.amazon.com/IAM/latest/UserGuide/access-analyzer-policy-validation.html) in the *IAM User Guide*. + **Require multi-factor authentication (MFA)** – If you have a scenario that requires IAM users or a root user in your AWS account, turn on MFA for additional security. To require MFA when API operations are called, add MFA conditions to your policies. For more information, see [ Secure API access with MFA](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_mfa_configure-api-require.html) in the *IAM User Guide*. For more information about best practices in IAM, see [Security best practices in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) in the *IAM User Guide*. ## Policy examples The following example customer-defined policies grant permissions for common scenarios. **Topics** + [Allow users to view their own permissions](#security_iam_id-based-policy-examples-view-own-permissions) To learn how to create an IAM identity-based policy using these example JSON policy documents, see [Creating policies on the JSON tab](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-json-editor) in the *IAM User Guide*. ### Allow users to view their own permissions This example shows how you might create a policy that allows IAM users to view the inline and managed policies that are attached to their user identity. This policy includes permissions to complete this action on the console or programmatically using the AWS CLI or AWS API. ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "ViewOwnUserInfo", "Effect": "Allow", "Action": [ "iam:GetUserPolicy", "iam:ListGroupsForUser", "iam:ListAttachedUserPolicies", "iam:ListUserPolicies", "iam:GetUser" ], "Resource": ["arn:aws:iam::*:user/${aws:username}"] }, { "Sid": "NavigateInConsole", "Effect": "Allow", "Action": [ "iam:GetGroupPolicy", "iam:GetPolicyVersion", "iam:GetPolicy", "iam:ListAttachedGroupPolicies", "iam:ListGroupPolicies", "iam:ListPolicyVersions", "iam:ListPolicies", "iam:ListUsers" ], "Resource": "*" } ] } ``` # Authorize core devices to interact with AWS services AWS IoT Greengrass core devices use the AWS IoT Core credentials provider to authorize calls to AWS services. The AWS IoT Core credentials provider enables devices to use their X.509 certificates as the unique device identity to authenticate AWS requests. This eliminates the need to store an AWS access key ID and secret access key on your AWS IoT Greengrass core devices. 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*. When you run the AWS IoT Greengrass Core software, you can choose to provision the AWS resources that the core device requires. This includes the AWS Identity and Access Management (IAM) role that your core device assumes through the AWS IoT Core credentials provider. Use the `--provision true` argument to configure a role and policies that allow the core device to get temporary AWS credentials. This argument also configures an AWS IoT role alias that points to this IAM role. You can specify the name of the IAM role and AWS IoT role alias to use. If you specify `--provision true` without these other name parameters, the Greengrass core device creates and uses the following default resources: + IAM role: `GreengrassV2TokenExchangeRole` This role has a policy named `GreengrassV2TokenExchangeRoleAccess` and a trust relationship that allows `credentials.iot.amazonaws.com` to assume the role. The policy includes the minimum permissions for the core device. **Important** This policy doesn't include access to files in S3 buckets. You must add permissions to the role to allow core devices to retrieve component artifacts from S3 buckets. For more information, see [Allow access to S3 buckets for component artifacts](#device-service-role-access-s3-bucket). + AWS IoT role alias: `GreengrassV2TokenExchangeRoleAlias` This role alias refers to the IAM role. For more information, see [Step 3: Install the AWS IoT Greengrass Core software](install-greengrass-v2.md). You can also set the role alias for an existing core device. To do so, configure the `iotRoleAlias` configuration parameter of the [Greengrass nucleus component](greengrass-nucleus-component.md). You can acquire temporary AWS credentials for this IAM role to perform AWS operations in your custom components. For more information, see [Interact with AWS services](interact-with-aws-services.md). **Topics** + [Service role permissions for core devices](#device-service-role-permissions) + [Allow access to S3 buckets for component artifacts](#device-service-role-access-s3-bucket) ## Service role permissions for core devices The role allows the following service to assume the role: + `credentials.iot.amazonaws.com` If you use the AWS IoT Greengrass Core software to create this role, it uses the following permissions policy to allow core devices to connect and send logs to AWS. The policy's name defaults to the name of the IAM role ending with `Access`. For example, if you use the default IAM role name, then this policy's name is `GreengrassV2TokenExchangeRoleAccess`. ------ #### [ Greengrass nucleus v2.5.0 and later ] ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents", "logs:DescribeLogStreams", "s3:GetBucketLocation" ], "Resource": "*" } ] } ``` ------ ------ #### [ v2.4.x ] ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:DescribeCertificate", "logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents", "logs:DescribeLogStreams", "s3:GetBucketLocation" ], "Resource": "*" } ] } ``` ------ ------ #### [ Earlier than v2.4.0 ] ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "iot:DescribeCertificate", "logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents", "logs:DescribeLogStreams", "iot:Connect", "iot:Publish", "iot:Subscribe", "iot:Receive", "s3:GetBucketLocation" ], "Resource": "*" } ] } ``` ------ ------ ## Allow access to S3 buckets for component artifacts The default core device role doesn't allow core devices to access S3 buckets. To deploy components that have artifacts in S3 buckets, you must add the `s3:GetObject` permission to allow core devices to download component artifacts. You can add a new policy to the core device role to grant this permission. **To add a policy that allows access to component artifacts in Amazon S3** 1. Create a file called `component-artifact-policy.json` and copy the following JSON into the file. This policy allows access to all files in an S3 bucket. Replace amzn-s3-demo-bucket with the name of the S3 bucket to allow the core device to access. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:GetObject" ], "Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*" } ] } ``` ------ 1. Run the following command to create the policy from the policy document in `component-artifact-policy.json`. ------ #### [ Linux or Unix ] ``` aws iam create-policy \ --policy-name MyGreengrassV2ComponentArtifactPolicy \ --policy-document file://component-artifact-policy.json ``` ------ #### [ Windows Command Prompt (CMD) ] ``` aws iam create-policy ^ --policy-name MyGreengrassV2ComponentArtifactPolicy ^ --policy-document file://component-artifact-policy.json ``` ------ #### [ PowerShell ] ``` aws iam create-policy ` --policy-name MyGreengrassV2ComponentArtifactPolicy ` --policy-document file://component-artifact-policy.json ``` ------ Copy the policy Amazon Resource Name (ARN) from the policy metadata in the output. You use this ARN to attach this policy to the core device role in the next step. 1. Run the following command to attach the policy to the core device role. Replace *GreengrassV2TokenExchangeRole* with the name of the role that you specified when you ran the AWS IoT Greengrass Core software. Then, replace the policy ARN with the ARN from the previous step. ------ #### [ Linux or Unix ] ``` aws iam attach-role-policy \ --role-name GreengrassV2TokenExchangeRole \ --policy-arn arn:aws:iam::123456789012:policy/MyGreengrassV2ComponentArtifactPolicy ``` ------ #### [ Windows Command Prompt (CMD) ] ``` aws iam attach-role-policy ^ --role-name GreengrassV2TokenExchangeRole ^ --policy-arn arn:aws:iam::123456789012:policy/MyGreengrassV2ComponentArtifactPolicy ``` ------ #### [ PowerShell ] ``` aws iam attach-role-policy ` --role-name GreengrassV2TokenExchangeRole ` --policy-arn arn:aws:iam::123456789012:policy/MyGreengrassV2ComponentArtifactPolicy ``` ------ If the command has no output, it succeeded, and your core device can access artifacts that you upload to this S3 bucket. # Minimal IAM policy for installer to provision resources When you install the AWS IoT Greengrass Core software, you can provision required AWS resources, such as an AWS IoT thing and an IAM role for your device. You can also deploy local development tools to the device. The installer requires AWS credentials so that it can perform these actions in your AWS account. For more information, see [Install the AWS IoT Greengrass Core software](install-greengrass-core-v2.md). The following example policy includes the minimum set of actions that the installer requires to provision these resources. These permissions are required if you specify the `--provision` argument for the installer. Replace *account-id* with your AWS account ID, and replace *GreengrassV2TokenExchangeRole* with the name of the token exchange role that you specify with the `--tes-role-name` [installer argument](configure-installer.md). **Note** The `DeployDevTools` policy statement is required only if you specify the `--deploy-dev-tools` argument for the installer. ------ #### [ Greengrass nucleus v2.5.0 and later ] ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "CreateTokenExchangeRole", "Effect": "Allow", "Action": [ "iam:AttachRolePolicy", "iam:CreatePolicy", "iam:CreateRole", "iam:GetPolicy", "iam:GetRole", "iam:PassRole" ], "Resource": [ "arn:aws:iam::123456789012:role/GreengrassV2TokenExchangeRole", "arn:aws:iam::123456789012:policy/GreengrassV2TokenExchangeRoleAccess", "arn:aws:iam::aws:policy/GreengrassV2TokenExchangeRoleAccess" ] }, { "Sid": "CreateIoTResources", "Effect": "Allow", "Action": [ "iot:AddThingToThingGroup", "iot:AttachPolicy", "iot:AttachThingPrincipal", "iot:CreateKeysAndCertificate", "iot:CreatePolicy", "iot:CreateRoleAlias", "iot:CreateThing", "iot:CreateThingGroup", "iot:DescribeEndpoint", "iot:DescribeRoleAlias", "iot:DescribeThingGroup", "iot:GetPolicy" ], "Resource": "*" }, { "Sid": "DeployDevTools", "Effect": "Allow", "Action": [ "greengrass:CreateDeployment", "iot:CancelJob", "iot:CreateJob", "iot:DeleteThingShadow", "iot:DescribeJob", "iot:DescribeThing", "iot:DescribeThingGroup", "iot:GetThingShadow", "iot:UpdateJob", "iot:UpdateThingShadow" ], "Resource": "*" } ] } ``` ------ ------ #### [ Earlier than v2.5.0 ] ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "CreateTokenExchangeRole", "Effect": "Allow", "Action": [ "iam:AttachRolePolicy", "iam:CreatePolicy", "iam:CreateRole", "iam:GetPolicy", "iam:GetRole", "iam:PassRole" ], "Resource": [ "arn:aws:iam::123456789012:role/GreengrassV2TokenExchangeRole", "arn:aws:iam::123456789012:policy/GreengrassV2TokenExchangeRoleAccess", "arn:aws:iam::aws:policy/GreengrassV2TokenExchangeRoleAccess" ] }, { "Sid": "CreateIoTResources", "Effect": "Allow", "Action": [ "iot:AddThingToThingGroup", "iot:AttachPolicy", "iot:AttachThingPrincipal", "iot:CreateKeysAndCertificate", "iot:CreatePolicy", "iot:CreateRoleAlias", "iot:CreateThing", "iot:CreateThingGroup", "iot:DescribeEndpoint", "iot:DescribeRoleAlias", "iot:DescribeThingGroup", "iot:GetPolicy" ], "Resource": "*" }, { "Sid": "DeployDevTools", "Effect": "Allow", "Action": [ "greengrass:CreateDeployment", "iot:CancelJob", "iot:CreateJob", "iot:DeleteThingShadow", "iot:DescribeJob", "iot:DescribeThing", "iot:DescribeThingGroup", "iot:GetThingShadow", "iot:UpdateJob", "iot:UpdateThingShadow" ], "Resource": "*" } ] } ``` ------ ------ # Greengrass service role The Greengrass service role is an AWS Identity and Access Management (IAM) service role that authorizes AWS IoT Greengrass to access resources from AWS services on your behalf. This role makes it possible for AWS IoT Greengrass to verify the identity of client devices and manage core device connectivity information. **Note** AWS IoT Greengrass V1 also uses this role to perform essential tasks. For more information, see [Greengrass service role](https://docs.aws.amazon.com/greengrass/v1/developerguide/service-role.html) in the *AWS IoT Greengrass V1 Developer Guide*. To allow AWS IoT Greengrass to access your resources, the Greengrass service role must be associated with your AWS account and specify AWS IoT Greengrass as a trusted entity. The role must include the [AWSGreengrassResourceAccessRolePolicy](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/service-role/AWSGreengrassResourceAccessRolePolicy) managed policy or a custom policy that defines equivalent permissions for the AWS IoT Greengrass features that you use. AWS maintains this policy, which defines the set of permissions that AWS IoT Greengrass uses to access your AWS resources. For more information, see [AWS managed policy: AWSGreengrassResourceAccessRolePolicy](security-iam-aws-managed-policies.md#aws-managed-policies-AWSGreengrassResourceAccessRolePolicy). You can reuse the same Greengrass service role across AWS Regions, but you must associate it with your account in every AWS Region where you use AWS IoT Greengrass. If the service role isn't configured in the current AWS Region, core devices fail to verify client devices and fail to update connectivity information. The following sections describe how to create and manage the Greengrass service role with the AWS Management Console or AWS CLI. **Topics** + [Manage the Greengrass service role (console)](#manage-greengrass-service-role-console) + [Manage the Greengrass service role (CLI)](#manage-service-role-cli) + [See also](#service-role-see-also) **Note** In addition to the service role that authorizes service-level access, you assign a *token exchange role* to Greengrass core devices. The token exchange role is a separate IAM role that controls how Greengrass components and Lambda functions on the core device can access AWS services. For more information, see [Authorize core devices to interact with AWS services](device-service-role.md). ## Manage the Greengrass service role (console) The AWS IoT console makes it easy to manage your Greengrass service role. For example, when you configure client device discovery for a core device, the console checks whether your AWS account is attached to a Greengrass service role in the current AWS Region. If not, the console can create and configure a service role for you. For more information, see [Create the Greengrass service role (console)](#create-greengrass-service-role-console). You can use the console for the following role management tasks: **Topics** + [Find your Greengrass service role (console)](#get-greengrass-service-role-console) + [Create the Greengrass service role (console)](#create-greengrass-service-role-console) + [Change the Greengrass service role (console)](#update-greengrass-service-role-console) + [Detach the Greengrass service role (console)](#remove-greengrass-service-role-console) **Note** The user who is signed in to the console must have permissions to view, create, or change the service role. ### Find your Greengrass service role (console) Use the following steps to find the service role that AWS IoT Greengrass uses in the current AWS Region. 1. Navigate to the [AWS IoT console](https://console.aws.amazon.com/iot). 1. In the navigation pane, choose **Settings**. 1. Scroll to the **Greengrass service role** section to see your service role and its policies. If you don't see a service role, the console can create or configure one for you. For more information, see [Create the Greengrass service role](#create-greengrass-service-role-console). ### Create the Greengrass service role (console) The console can create and configure a default Greengrass service role for you. This role has the following properties. | Property | Value | | --- | --- | | Name | Greengrass\$1ServiceRole | | Trusted entity | AWS service: greengrass | | Policy | [AWSGreengrassResourceAccessRolePolicy](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/service-role/AWSGreengrassResourceAccessRolePolicy) | **Note** If you create this role with the [AWS IoT Greengrass V1 device setup script](https://docs.aws.amazon.com/greengrass/v1/developerguide/quick-start.html), the role name is `GreengrassServiceRole_random-string`. When you configure client device discovery for a core device, the console checks whether a Greengrass service role is associated with your AWS account in the current AWS Region. If not, the console prompts you to allow AWS IoT Greengrass to read and write to AWS services on your behalf. If you grant permission, the console checks whether a role named `Greengrass_ServiceRole` exists in your AWS account. + If the role exists, the console attaches the service role to your AWS account in the current AWS Region. + If the role doesn't exist, the console creates a default Greengrass service role and attaches it to your AWS account in the current AWS Region. **Note** If you want to create a service role with custom role policies, use the IAM console to create or modify the role. For more information, see [Creating a role to delegate permissions to an AWS service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html) or [Modifying a role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_manage_modify.html) in the *IAM User Guide*. Make sure that the role grants permissions that are equivalent to the `AWSGreengrassResourceAccessRolePolicy` managed policy for the features and resources that you use. We recommend that you also include the `aws:SourceArn` and `aws:SourceAccount` global condition context keys in your trust policy to help prevent the *confused deputy* security problem. The condition context keys restrict access to allow only those requests that come from the specified account and Greengrass workspace. For more information about the confused deputy problem, see [Cross-service confused deputy prevention](cross-service-confused-deputy-prevention.md). If you create a service role, return to the AWS IoT console and attach the role to your AWS account. You can do this under **Greengrass service role** on the **Settings** page. ### Change the Greengrass service role (console) Use the following procedure to choose a different Greengrass service role to attach to your AWS account in the AWS Region currently selected in the console. 1. Navigate to the [AWS IoT console](https://console.aws.amazon.com/iot). 1. In the navigation pane, choose **Settings**. 1. Under **Greengrass service role**, choose **Change role**. The **Update Greengrass service role** dialog box opens and shows the IAM roles in your AWS account that define AWS IoT Greengrass as a trusted entity. 1. Choose the Greengrass service role to attach. 1. Choose **Attach role**. ### Detach the Greengrass service role (console) Use the following procedure to detach the Greengrass service role from your AWS account in the current AWS Region. This revokes permissions for AWS IoT Greengrass to access AWS services in the current AWS Region. **Important** Detaching the service role might interrupt active operations. 1. Navigate to the [AWS IoT console](https://console.aws.amazon.com/iot). 1. In the navigation pane, choose **Settings**. 1. Under **Greengrass service role**, choose **Detach role**. 1. In the confirmation dialog box, choose **Detach**. **Note** If you no longer need the role, you can delete it in the IAM console. For more information, see [Deleting roles or instance profiles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_manage_delete.html) in the *IAM User Guide*. Other roles might allow AWS IoT Greengrass to access your resources. To find all roles that allow AWS IoT Greengrass to assume permissions on your behalf, in the IAM console, on the **Roles** page, look for roles that include **AWS service: greengrass** in the **Trusted entities** column. ## Manage the Greengrass service role (CLI) In the following procedures, we assume that the AWS Command Line Interface is installed and configured to use your AWS account. For more information, see [Installing, updating, and uninstalling the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/installing.html) and [Configuring the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html) in the *AWS Command Line Interface User Guide*. You can use the AWS CLI for the following role management tasks: **Topics** + [Get the Greengrass service role (CLI)](#get-service-role) + [Create the Greengrass service role (CLI)](#create-service-role) + [Remove the Greengrass service role (CLI)](#remove-service-role) ### Get the Greengrass service role (CLI) Use the following procedure to find out if a Greengrass service role is associated with your AWS account in an AWS Region. + Get the service role. Replace *region* with your AWS Region (for example, `us-west-2`). ``` aws greengrassv2 get-service-role-for-account --region region ``` If a Greengrass service role is already associated with your account, the request returns the following role metadata. ``` { "associatedAt": "timestamp", "roleArn": "arn:aws:iam::account-id:role/path/role-name" } ``` If the request doesn't return role metadata, then you must create the service role (if it doesn't exist) and associate it with your account in the AWS Region. ### Create the Greengrass service role (CLI) Use the following steps to create a role and associate it with your AWS account. **To create the service role using IAM** 1. Create a role with a trust policy that allows AWS IoT Greengrass to assume the role. This example creates a role named `Greengrass_ServiceRole`, but you can use a different name. We recommend that you also include the `aws:SourceArn` and `aws:SourceAccount` global condition context keys in your trust policy to help prevent the *confused deputy* security problem. The condition context keys restrict access to allow only those requests that come from the specified account and Greengrass workspace. For more information about the confused deputy problem, see [Cross-service confused deputy prevention](cross-service-confused-deputy-prevention.md). ------ #### [ Linux or Unix ] ``` aws iam create-role --role-name Greengrass_ServiceRole --assume-role-policy-document '{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "greengrass.amazonaws.com" }, "Action": "sts:AssumeRole", "Condition": { "ArnLike": { "aws:SourceArn": "arn:aws:greengrass:region:account-id:*" }, "StringEquals": { "aws:SourceAccount": "account-id" } } } ] }' ``` ------ #### [ Windows Command Prompt (CMD) ] ``` aws iam create-role --role-name Greengrass_ServiceRole --assume-role-policy-document "{\"Version\":\"2012-10-17\", \"Statement\":[{\"Effect\":\"Allow\",\"Principal\":{\"Service\":\"greengrass.amazonaws.com\"},\"Action\":\"sts:AssumeRole\",\"Condition\":{\"ArnLike\":{\"aws:SourceArn\":\"arn:aws:greengrass:region:account-id:*\"},\"StringEquals\":{\"aws:SourceAccount\":\"account-id\"}}}]}" ``` ------ #### [ PowerShell ] ``` aws iam create-role --role-name Greengrass_ServiceRole --assume-role-policy-document '{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "greengrass.amazonaws.com" }, "Action": "sts:AssumeRole", "Condition": { "ArnLike": { "aws:SourceArn": "arn:aws:greengrass:region:account-id:*" }, "StringEquals": { "aws:SourceAccount": "account-id" } } } ] }' ``` ------ 1. Copy the role ARN from the role metadata in the output. You use the ARN to associate the role with your account. 1. Attach the `AWSGreengrassResourceAccessRolePolicy` policy to the role. ``` aws iam attach-role-policy --role-name Greengrass_ServiceRole --policy-arn arn:aws:iam::aws:policy/service-role/AWSGreengrassResourceAccessRolePolicy ``` **To associate the service role with your AWS account** + Associate the role with your account. Replace *role-arn* with the service role ARN and *region* with your AWS Region (for example, `us-west-2`). ``` aws greengrassv2 associate-service-role-to-account --role-arn role-arn --region region ``` If successful, the request returns the following response. ``` { "associatedAt": "timestamp" } ``` ### Remove the Greengrass service role (CLI) Use the following steps to disassociate the Greengrass service role from your AWS account. + Disassociate the service role from your account. Replace *region* with your AWS Region (for example, `us-west-2`). ``` aws greengrassv2 disassociate-service-role-from-account --region region ``` If successful, the following response is returned. ``` { "disassociatedAt": "timestamp" } ``` **Note** You should delete the service role if you're not using it in any AWS Region. First use [https://docs.aws.amazon.com/cli/latest/reference/iam/delete-role-policy.html](https://docs.aws.amazon.com/cli/latest/reference/iam/delete-role-policy.html) to detach the `AWSGreengrassResourceAccessRolePolicy` managed policy from the role, and then use [https://docs.aws.amazon.com/cli/latest/reference/iam/delete-role.html](https://docs.aws.amazon.com/cli/latest/reference/iam/delete-role.html) to delete the role. For more information, see [Deleting roles or instance profiles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_manage_delete.html) in the *IAM User Guide*. ## See also + [Creating a role to delegate permissions to an AWS service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html) in the *IAM User Guide* + [Modifying a role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_manage_modify.html) in the *IAM User Guide* + [Deleting roles or instance profiles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_manage_delete.html) in the *IAM User Guide* + AWS IoT Greengrass commands in the *AWS CLI Command Reference* + [associate-service-role-to-account](https://docs.aws.amazon.com/cli/latest/reference/greengrassv2/associate-service-role-to-account.html) + [disassociate-service-role-from-account](https://docs.aws.amazon.com/cli/latest/reference/greengrassv2/disassociate-service-role-from-account.html) + [get-service-role-for-account](https://docs.aws.amazon.com/cli/latest/reference/greengrassv2/get-service-role-for-account.html) + IAM commands in the *AWS CLI Command Reference* + [attach-role-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/attach-role-policy.html) + [create-role](https://docs.aws.amazon.com/cli/latest/reference/iam/create-role.html) + [delete-role](https://docs.aws.amazon.com/cli/latest/reference/iam/delete-role.html) + [delete-role-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/delete-role-policy.html) # AWS managed policies for AWS IoT Greengrass An AWS managed policy is a standalone policy that is created and administered by AWS. AWS managed policies are designed to provide permissions for many common use cases so that you can start assigning permissions to users, groups, and roles. Keep in mind that AWS managed policies might not grant least-privilege permissions for your specific use cases because they're available for all AWS customers to use. We recommend that you reduce permissions further by defining [ customer managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#customer-managed-policies) that are specific to your use cases. You cannot change the permissions defined in AWS managed policies. If AWS updates the permissions defined in an AWS managed policy, the update affects all principal identities (users, groups, and roles) that the policy is attached to. AWS is most likely to update an AWS managed policy when a new AWS service is launched or new API operations become available for existing services. For more information, see [AWS managed policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#aws-managed-policies) in the *IAM User Guide*. **Topics** + [AWS managed policy: AWSGreengrassFullAccess](#aws-managed-policies-AWSGreengrassFullAccess) + [AWS managed policy: AWSGreengrassReadOnlyAccess](#aws-managed-policies-AWSGreengrassReadOnlyAccess) + [AWS managed policy: AWSGreengrassResourceAccessRolePolicy](#aws-managed-policies-AWSGreengrassResourceAccessRolePolicy) + [AWS IoT Greengrass updates to AWS managed policies](#aws-managed-policy-updates) ## AWS managed policy: AWSGreengrassFullAccess You can attach the `AWSGreengrassFullAccess` policy to your IAM identities. This policy grants administrative permissions that allow a principal full access to all AWS IoT Greengrass actions. **Permissions details** This policy includes the following permissions: + `greengrass` – Allows principals full access to all AWS IoT Greengrass actions. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "greengrass:*" ], "Resource": "*" } ] } ``` ------ ## AWS managed policy: AWSGreengrassReadOnlyAccess You can attach the `AWSGreengrassReadOnlyAccess` policy to your IAM identities. This policy grants read-only permissions that allow a principal to view, but not modify, information in AWS IoT Greengrass. For example, principals with these permissions can view the list of components deployed to a Greengrass core device, but can't create a deployment to change the components that run on that device. **Permissions details** This policy includes the following permissions: + `greengrass` – Allows principals to perform actions that return either a list of items or details about an item. This includes API operations that start with `List` or `Get`. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "greengrass:List*", "greengrass:Get*" ], "Resource": "*" } ] } ``` ------ ## AWS managed policy: AWSGreengrassResourceAccessRolePolicy You can attach the `AWSGreengrassResourceAccessRolePolicy` policy to your IAM entities. AWS IoT Greengrass also attaches this policy to a service role that allows AWS IoT Greengrass to perform actions on your behalf. For more information, see [Greengrass service role](greengrass-service-role.md). This policy grants administrative permissions that allow AWS IoT Greengrass to perform essential tasks, such as retrieving your Lambda functions, managing AWS IoT device shadows, and verifying Greengrass client devices. **Permissions details** This policy includes the following permissions. + `greengrass` – Manage Greengrass resources. + `iot` (`*Shadow`) – Manage AWS IoT shadows that have the following special identifiers in their names. These permissions are required so that AWS IoT Greengrass can communicate with core devices. + `*-gci` – AWS IoT Greengrass uses this shadow to store core device connectivity information, so client devices can discover and connect to core devices. + `*-gcm` – AWS IoT Greengrass V1 uses this shadow to notify the core device that the Greengrass group's certificate authority (CA) certificate has rotated. + `*-gda` – AWS IoT Greengrass V1 uses this shadow to notify the core device of a deployment. + `GG_*` – Unused. + `iot` (`DescribeThing` and `DescribeCertificate`) – Retrieve information about AWS IoT things and certificates. These permissions are required so that AWS IoT Greengrass can verify client devices that connect to a core device. For more information, see [Interact with local IoT devices](interact-with-local-iot-devices.md). + `lambda` – Retrieve information about AWS Lambda functions. This permission is required so that AWS IoT Greengrass V1 can deploy Lambda functions to Greengrass cores. For more information, see [Run Lambda function on the AWS IoT Greengrass core](https://docs.aws.amazon.com/greengrass/v1/developerguide/lambda-functions.html) in the *AWS IoT Greengrass V1 Developer Guide*. + `secretsmanager` – Retrieve the value of AWS Secrets Manager secrets whose names start with `greengrass-`. This permission is required so that AWS IoT Greengrass V1 can deploy Secrets Manager secrets to Greengrass cores. For more information, see [Deploy secrets to the AWS IoT Greengrass core](https://docs.aws.amazon.com/greengrass/v1/developerguide/secrets.html) in the *AWS IoT Greengrass V1 Developer Guide*. + `s3` – Retrieve files objects from S3 buckets whose names contain `greengrass` or `sagemaker`. These permissions are required so that AWS IoT Greengrass V1 can deploy machine learning resources that you store in S3 buckets. For more information, see [Machine learning resources](https://docs.aws.amazon.com/greengrass/v1/developerguide/ml-inference.html#ml-resources) in the *AWS IoT Greengrass V1 Developer Guide*. + `sagemaker` – Retrieve information about Amazon SageMaker AI machine learning inference models. This permission is required so that AWS IoT Greengrass V1 can deploy ML models to Greengrass cores. For more information, see [Perform machine learning inference](https://docs.aws.amazon.com/greengrass/v1/developerguide/ml-inference.html) in the *AWS IoT Greengrass V1 Developer Guide*. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowGreengrassAccessToShadows", "Action": [ "iot:DeleteThingShadow", "iot:GetThingShadow", "iot:UpdateThingShadow" ], "Effect": "Allow", "Resource": [ "arn:aws:iot:*:*:thing/GG_*", "arn:aws:iot:*:*:thing/*-gcm", "arn:aws:iot:*:*:thing/*-gda", "arn:aws:iot:*:*:thing/*-gci" ] }, { "Sid": "AllowGreengrassToDescribeThings", "Action": [ "iot:DescribeThing" ], "Effect": "Allow", "Resource": "arn:aws:iot:*:*:thing/*" }, { "Sid": "AllowGreengrassToDescribeCertificates", "Action": [ "iot:DescribeCertificate" ], "Effect": "Allow", "Resource": "arn:aws:iot:*:*:cert/*" }, { "Sid": "AllowGreengrassToCallGreengrassServices", "Action": [ "greengrass:*" ], "Effect": "Allow", "Resource": "*" }, { "Sid": "AllowGreengrassToGetLambdaFunctions", "Action": [ "lambda:GetFunction", "lambda:GetFunctionConfiguration" ], "Effect": "Allow", "Resource": "*" }, { "Sid": "AllowGreengrassToGetGreengrassSecrets", "Action": [ "secretsmanager:GetSecretValue" ], "Effect": "Allow", "Resource": "arn:aws:secretsmanager:*:*:secret:greengrass-*" }, { "Sid": "AllowGreengrassAccessToS3Objects", "Action": [ "s3:GetObject" ], "Effect": "Allow", "Resource": [ "arn:aws:s3:::*Greengrass*", "arn:aws:s3:::*GreenGrass*", "arn:aws:s3:::*greengrass*", "arn:aws:s3:::*Sagemaker*", "arn:aws:s3:::*SageMaker*", "arn:aws:s3:::*sagemaker*" ] }, { "Sid": "AllowGreengrassAccessToS3BucketLocation", "Action": [ "s3:GetBucketLocation" ], "Effect": "Allow", "Resource": "*" }, { "Sid": "AllowGreengrassAccessToSageMakerTrainingJobs", "Action": [ "sagemaker:DescribeTrainingJob" ], "Effect": "Allow", "Resource": [ "arn:aws:sagemaker:*:*:training-job/*" ] } ] } ``` ------ ## AWS IoT Greengrass updates to AWS managed policies You can view details about updates to AWS managed policies for AWS IoT Greengrass from the time this service began tracking these changes. For automatic alerts about changes to this page, subscribe to the RSS feed on the [AWS IoT Greengrass V2 document history page](document-history.md). | Change | Description | Date | | --- | --- | --- | | AWS IoT Greengrass started tracking changes | AWS IoT Greengrass started tracking changes for its AWS managed policies. | July 2, 2021 | # Cross-service confused deputy prevention The confused deputy problem is a security issue where an entity that doesn't have permission to perform an action can coerce a more-privileged entity to perform the action. In AWS, cross-service impersonation can result in the confused deputy problem. Cross-service impersonation can occur when one service (the *calling service*) calls another service (the *called service*). The calling service can be manipulated to use its permissions to act on another customer's resources in a way it should not otherwise have permission to access. To prevent this, AWS provides tools that help you protect your data for all services with service principals that have been given access to resources in your account. We recommend using the [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourcearn](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourcearn) and [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceaccount](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceaccount) global condition context keys in resource policies to limit the permissions that AWS IoT Greengrass gives another service to the resource. If you use both global condition context keys, the `aws:SourceAccount` value and the account in the `aws:SourceArn` value must use the same account ID when used in the same policy statement. The value of `aws:SourceArn` must be the Greengrass customer resource that is associated with the `sts:AssumeRole` request. The most effective way to protect against the confused deputy problem is to use the `aws:SourceArn` global condition context key with the full ARN of the resource. If you don't know the full ARN of the resource or if you are specifying multiple resources, use the `aws:SourceArn` global context condition key with wildcards (`*`) for the unknown portions of the ARN. For example, `arn:aws:greengrass::account-id:*`. For an example of a policy that uses the `aws:SourceArn` and `aws:SourceAccount` global condition context keys, see [Create the Greengrass service role](greengrass-service-role.md#create-service-role). # Troubleshooting identity and access issues for AWS IoT Greengrass Use the following information to help you diagnose and fix common issues that you might encounter when working with AWS IoT Greengrass and IAM. **Topics** + [I'm not authorized to perform an action in AWS IoT Greengrass](#security_iam_troubleshoot-no-permissions) + [I'm not authorized to perform iam:PassRole](#security_iam_troubleshoot-passrole) + [I'm an administrator and want to allow others to access AWS IoT Greengrass](#security_iam_troubleshoot-admin-delegate) + [I want to allow people outside of my AWS account to access my AWS IoT Greengrass resources](#security_iam_troubleshoot-cross-account-access) For general troubleshooting help, see [Troubleshooting AWS IoT Greengrass V2](troubleshooting.md). ## I'm not authorized to perform an action in AWS IoT Greengrass If you receive an error that states you're not authorized to perform an action, you must contact your administrator for assistance. Your administrator is the person who provided you with your user name and password. The following example error occurs when the `mateojackson` IAM user tries to view details about a core device, but does not have `greengrass:GetCoreDevice` permissions. ``` User: arn:aws:iam::123456789012:user/mateojackson is not authorized to perform: greengrass:GetCoreDevice on resource: arn:aws:greengrass:us-west-2:123456789012:coreDevices/MyGreengrassCore ``` In this case, Mateo asks his administrator to update his policies to allow him to access the `arn:aws:greengrass:us-west-2:123456789012:coreDevices/MyGreengrassCore` resource using the `greengrass:GetCoreDevice` action. The following are general IAM issues that you might encounter when working with AWS IoT Greengrass. ## I'm not authorized to perform iam:PassRole If you receive an error that you're not authorized to perform the `iam:PassRole` action, your policies must be updated to allow you to pass a role to AWS IoT Greengrass. Some AWS services allow you to pass an existing role to that service instead of creating a new service role or service-linked role. To do this, you must have permissions to pass the role to the service. The following example error occurs when an IAM user named `marymajor` tries to use the console to perform an action in AWS IoT Greengrass. However, the action requires the service to have permissions that are granted by a service role. Mary does not have permissions to pass the role to the service. ``` User: arn:aws:iam::123456789012:user/marymajor is not authorized to perform: iam:PassRole ``` In this case, Mary's policies must be updated to allow her to perform the `iam:PassRole` action. If you need help, contact your AWS administrator. Your administrator is the person who provided you with your sign-in credentials. ## I'm an administrator and want to allow others to access AWS IoT Greengrass To allow others to access AWS IoT Greengrass, you must grant permission to the people or applications that need access. If you are using AWS IAM Identity Center to manage people and applications, you assign permission sets to users or groups to define their level of access. Permission sets automatically create and assign IAM policies to IAM roles that are associated with the person or application. For more information, see [Permission sets](https://docs.aws.amazon.com/singlesignon/latest/userguide/permissionsetsconcept.html) in the *AWS IAM Identity Center User Guide*. If you are not using IAM Identity Center, you must create IAM entities (users or roles) for the people or applications that need access. You must then attach a policy to the entity that grants them the correct permissions in AWS IoT Greengrass. After the permissions are granted, provide the credentials to the user or application developer. They will use those credentials to access AWS. To learn more about creating IAM users, groups, policies, and permissions, see [IAM Identities](https://docs.aws.amazon.com/IAM/latest/UserGuide/id.html) and [Policies and permissions in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) in the *IAM User Guide*. ## I want to allow people outside of my AWS account to access my AWS IoT Greengrass resources You can create an IAM role that users in other accounts or people outside of your organization can use to access your AWS resources. You can specify the who is trusted to assume the role. For more information, see [Providing access to an IAM user in another AWS account that you own](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_aws-accounts.html) and [Providing access to AWS accounts owned by third parties](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_third-party.html) in the *IAM User Guide*. AWS IoT Greengrass doesn't support cross-account access based on resource-based policies or access control lists (ACLs). # Allow device traffic through a proxy or firewall Greengrass core devices and Greengrass components perform outbound requests to AWS services and other websites. As a security measure, you might limit outbound traffic to a small range of endpoints and ports. You can use the following information about endpoints and ports to limit device traffic through a proxy, firewall, or [Amazon VPC security group](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html). For more information about how to configure a core device to use a proxy, see [Connect on port 443 or through a network proxy](configure-greengrass-core-v2.md#configure-alpn-network-proxy). **Topics** + [Endpoints for basic operation](#core-endpoints) + [Endpoints for installation with automatic provisioning](#automatic-provisioning-endpoints) + [Endpoints for AWS-provided components](#public-component-endpoints) ## Endpoints for basic operation Greengrass core devices use the following endpoints and ports for basic operation. ### 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" } ``` | Endpoint | Port | Required | Description | | --- | --- | --- | --- | | `greengrass-ats.iot.region.amazonaws.com` | 8443 or 443 | Yes | Used for data plane operations, such as installing deployments and working with client devices. | | `device-data-prefix-ats.iot.region.amazonaws.com` | MQTT: 8883 or 443 HTTPS: 8443 or 443 | Yes | Used for data plane operations for device management, such as MQTT communication and shadow sync with AWS IoT Core. | | `device-credentials-prefix.credentials.iot.region.amazonaws.com` | 443 | Yes | Used to acquire AWS credentials, which the core device uses to download component artifacts from Amazon S3 and perform other operations. For more information, see [Authorize core devices to interact with AWS services](device-service-role.md). | | `*.s3.amazonaws.com` `*.s3.region.amazonaws.com` | 443 | Yes | Used for deployments. This format includes the `*` character, because endpoint prefixes are controlled internally and might change at any time. | | `data.iot.region.amazonaws.com` | 443 | No | Required if the core device runs a version of the [Greengrass nucleus](greengrass-nucleus-component.md) earlier than v2.4.0 and is configured to use a network proxy. The core device uses this endpoint for MQTT communication with AWS IoT Core when behind a proxy. For more information, see [Configure a network proxy](configure-greengrass-core-v2.md#configure-network-proxy). | ## Endpoints for installation with automatic provisioning Greengrass core devices use the following endpoints and ports when you [install the AWS IoT Greengrass Core software with automatic resource provisioning](quick-installation.md). | Endpoint | Port | Required | Description | | --- | --- | --- | --- | | `iot.region.amazonaws.com` | 443 | Yes | Used to create AWS IoT resources and retrieve information about existing AWS IoT resources. | | `iam.amazonaws.com` | 443 | Yes | Used to create IAM resources and retrieve information about existing IAM resources. | | `sts.region.amazonaws.com` | 443 | Yes | Used to get the ID of your AWS account. | | `greengrass.region.amazonaws.com` | 443 | No | Required if you use the `--deploy-dev-tools` argument to deploy the Greengrass CLI component to the core device. | ## Endpoints for AWS-provided components Greengrass core devices use additional endpoints depending on which software components they run. You can find the endpoints that each AWS-provided component requires in the **Requirements** section on each component's page in this developer guide. For more information, see [AWS-provided components](public-components.md). # Compliance validation for AWS IoT Greengrass To learn whether an AWS service is within the scope of specific compliance programs, see [AWS services in Scope by Compliance Program](https://aws.amazon.com/compliance/services-in-scope/) and choose the compliance program that you are interested in. For general information, see [AWS Compliance Programs](https://aws.amazon.com/compliance/programs/). You can download third-party audit reports using AWS Artifact. For more information, see [Downloading Reports in AWS Artifact](https://docs.aws.amazon.com/artifact/latest/ug/downloading-documents.html). Your compliance responsibility when using AWS services is determined by the sensitivity of your data, your company's compliance objectives, and applicable laws and regulations. For more information about your compliance responsibility when using AWS services, see [AWS Security Documentation](https://docs.aws.amazon.com/security/). # FIPS endpoints AWS IoT Greengrass supports the use of FIPS ([Federal Information Processing Standard (FIPS) 140-2](https://aws.amazon.com/compliance/fips/)) endpoints. When FIPS mode is enabled, all data transmissions, including both HTTP and MQTT protocols, to AWS Cloud services should invoke and establish connections with the corresponding FIPS-compliant endpoints ([FIPS - Amazon Web Services (AWS)](https://aws.amazon.com/compliance/fips/)). MQTT communications to AWS IoT utilize the IoT dataplane FIPS endpoint ([Connecting to AWS IoT FIPS endpoints - AWS IoT Core](https://docs.aws.amazon.com/iot/latest/developerguide/iot-connect-fips.html#iot-connect-fips-data)) and the AWS-developed FIPS-compliant cryptographic library aws-lc. For HTTP communications in Greengrass: + For nucleus and plugin components, all SDK HTTP clients are configured with FIPS endpoints by setting the system property AWS\$1USE\$1FIPS\$1ENDPOINT to true; + For generic components, all components start with the system property AWS\$1USE\$1FIPS\$1ENDPOINT set to true. This process ensures that the SDK HTTP clients used by these generic components send requests to FIPS-compliant endpoints. **Note** In the case of Stream manager, Nucleus passes the environment variable AWS\$1GG\$1FIPS\$1MODE. This environment variable allows the HTTP clients utilized within the Stream Manager to identify and connect to the corresponding FIPS-compliant endpoint. AWS IoT Greengrass offers two methods to enable FIPS mode: provisioning and deployment. To activate the FIPS mode, you have to set the configuration parameter `fipsMode` to true, Nucleus then sets the system property AWS\$1USE\$1FIPS\$1ENDPOINT to true and propagate it as an environment variable to all other components. Additionally, AWS IoT Greengrass will download a root CA certificate (CA3) and append it to the existing rootCA.pem (or AmazonRootCA1.pem) file. If you enable FIPS through a new deployment, Nucleus will restart to ensure that the system property takes effect after enabling FIPS mode. Apart from configuring the `fipsMode` parameter, you must also configure the `iotDataEndpoint`, `iotCredEndpoint` and `greengrassDataEndpoint` parameters. For more information, see the relevant document below. ## Enable FIPS endpoints with deployment 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. There are two endpoints required, the `iotDataEndpoint` and the `iotCredEndpoint`. Do the following: 1. Get the FIPS data endpoint for your region in the [AWS IoT Core FIPS data plane endpoints.](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#iot-core-data-plane-endpoints) The FIPS data endpoint for your AWS account should look like this: *data.iot-fips.us-west-2.amazonaws.com* 1. Get the FIPS credentials endpoint for your region in the [AWS IoT Core FIPS data plane endpoints.](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#iot-core-data-plane-endpoints) The FIPS credentials endpoint for your AWS account should look like this: *data.credentials.iot-fips.us-west-2.amazonaws.com* Then, to enable FIPS with a deployment, you need to apply the following configuration to Nucleus. The configuration to merge on the deployment is as follows. ------ #### [ Console ] **Configuration to merge** ``` { "fipsMode": "true", "iotDataEndpoint": "data.iot-fips.us-west-2.amazonaws.com", "greengrassDataPlaneEndpoint": "iotData", "iotCredEndpoint": "data.credentials.iot-fips.us-west-2.amazonaws.com" } ``` ------ #### [ AWS CLI ] The following command creates a deployment to a core device. ``` aws greengrassv2 create-deployment --cli-input-json file://dashboard-deployment.json ``` The `dashboard-deployment.json` file contains the following JSON document. ``` { "targetArn": "arn:aws:iot:us-west-2:123456789012:thing/MyGreengrassCore", "deploymentName": "Deployment for MyGreengrassCore", "components": { "aws.greengrass.Nucleus": { "componentVersion": "2.13.0", "configurationUpdate": { "merge":{\"fipsMode\":\"true\",\"iotDataEndpoint\":\"data.iot-fips.us-west-2.amazonaws.com\",\"greengrassDataPlaneEndpoint\":\"iotData\",\"iotCredEndpoint\":\"data.credentials.iot-fips.us-west-2.amazonaws.com\"}" } } } } ``` ------ #### [ Greengrass CLI ] The following [Greengrass CLI](greengrass-cli-component.md) command creates a local deployment on a core device. ``` sudo greengrass-cli deployment create \ --recipeDir recipes \ --artifactDir artifacts \ --merge "aws.greengrass.Nucleus=2.13.0" \ --update-config dashboard-configuration.json ``` The `dashboard-configuration.json` file contains the following JSON document. ``` { "aws.greengrass.Nucleus": { "MERGE": { "fipsMode": "true", "iotDataEndpoint": "data.iot-fips.us-west-2.amazonaws.com", "greengrassDataPlaneEndpoint": "iotData", "iotCredEndpoint": "data.credentials.iot-fips.us-west-2.amazonaws.com" } } } ``` ------ ## Install Nucleus with FIPS endpoints with manual resource provisioning Manually provision AWS resources for AWS IoT Greengrass V2 core devices with FIPS endpoints **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](#w2ab1c58c44c23b9) + [Create an AWS IoT thing](#create-iot-thing) + [Create the thing certificate](#create-thing-certificate-fips) + [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-fips) ### 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. There are two endpoints required, the `iotDataEndpoint` and the `iotCredEndpoint`. Do the following: 1. Get the FIPS data endpoint for your region in the [AWS IoT Core FIPS data plane endpoints.](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#iot-core-data-plane-endpoints) The FIPS data endpoint for your AWS account should look like this: *data.iot-fips.us-west-2.amazonaws.com* 1. Get the FIPS credentials endpoint for your region in the [AWS IoT Core FIPS data plane endpoints.](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#iot-core-data-plane-endpoints) The FIPS credentials endpoint for your AWS account should look like this: *data.credentials.iot-fips.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. Next, configure the thing certificate. For more information, see [Configure the thing certificate](manual-installation.md#configure-thing-certificate). ### 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. Download the CA1 certificate and the [CA3 certificate](https://www.amazontrust.com/repository/). ------ #### [ Linux or Unix ] + Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the Greengrass root folder. ``` sudo curl -o /greengrass/v2/AmazonRootCA1.pem https://www.amazontrust.com/repository/AmazonRootCA1.pem sudo curl -o - https://www.amazontrust.com/repository/AmazonRootCA3.pem >> /greengrass/v2/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. Download both the CA1 and the [CA3 certificate](https://www.amazontrust.com/repository/). ------ #### [ Linux or Unix ] + Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the Greengrass root folder. ``` sudo curl -o /greengrass/v2/AmazonRootCA1.pem https://www.amazontrust.com/repository/AmazonRootCA1.pem sudo curl -o - https://www.amazontrust.com/repository/AmazonRootCA3.pem >> /greengrass/v2/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" fipsMode: "true" iotDataEndpoint: "data.iot-fips.us-west-2.amazonaws.com" greengrassDataPlaneEndpoint: "iotData" iotCredEndpoint: "data.credentials.iot-fips.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. 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: "/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" fipsMode: "true" iotDataEndpoint: "data.iot-fips.us-west-2.amazonaws.com" greengrassDataPlaneEndpoint: "iotData" iotCredEndpoint: "data.credentials.iot-fips.us-west-2.amazonaws.com" ``` 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. 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). 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 FIPS endpoints with fleet provisioning This feature is available for v2.4.0 and later of the [Greengrass nucleus component](greengrass-nucleus-component.md). Install FIPS endpoints on your AWS IoT Greengrass Core software with AWS IoT fleet provisioning for your core devices. **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, [install the AWS IoT Greengrass Core software with manual provisioning](#FIPS-fleet-provisioning). 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-fleet-provisioning) + [Download the AWS IoT Greengrass Core software](#download-greengrass-core-v2-fleet) + [Download the AWS IoT fleet provisioning plugin](#download-fleet-provisioning-plugin) + [Install the AWS IoT Greengrass Core software](#run-greengrass-core-v2-installer-fleet-provisioning) ### 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 FIPS 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 FIPS data endpoint for your region in the [AWS IoT Core FIPS data plane endpoints.](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#iot-core-data-plane-endpoints) The FIPS data endpoint for your AWS account should look like this: *data.iot-fips.us-west-2.amazonaws.com* 1. Get the FIPS credentials endpoint for your region in the [AWS IoT Core FIPS data plane endpoints.](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#iot-core-data-plane-endpoints) The FIPS credentials endpoint for your AWS account should look like this: *data.credentials.iot-fips.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 both the CA1 certificate and the [CA3 certificate](https://www.amazontrust.com/repository/). ------ #### [ Linux or Unix ] ``` sudo curl -o - https://www.amazontrust.com/repository/AmazonRootCA3.pem >> /greengrass/v2/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" configuration: fipsMode: "true" greengrassDataPlaneEndpoint: "iotData" aws.greengrass.FleetProvisioningByClaim: configuration: rootPath: "/greengrass/v2" awsRegion: "us-west-2" iotDataEndpoint: "data.iot-fips.us-west-2.amazonaws.com" iotCredEndpoint: "data.credentials.iot-fips.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. 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) ## Install FIPS endpoints with auto 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. **Topics** + [Set up the device environment](#set-up-device-environment) + [Provide AWS credentials to the device](#provide-installer-aws-credentials-auto) + [Download the AWS IoT Greengrass Core software](#download-greengrass-core-v2-auto) + [Install the AWS IoT Greengrass Core software](#run-greengrass-core-v2-installer-auto) ### 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. 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. ``` --- services: aws.greengrass.Nucleus: configuration: fipsMode: "true" iotDataEndpoint: "data.iot-fips.us-west-2.amazonaws.com" iotCredEndpoint: "data.credentials.iot-fips.us-west-2.amazonaws.com" greengrassDataPlaneEndpoint: "iotData" ``` + Replace *us-west-2* with the AWS Region where you created the resources. + Replace the *iotDataEndpoint* with your AWS IoT data endpoint. + Replace the *iotCredEndpoint* with your AWS IoT credentials endpoint. 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 \ --init-config ./GreengrassInstaller/config.yaml \ --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. 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) ## FIPS compliance first party components | | | | --- | --- | | aws.greengrass.Nucleus | data.iot-fips.us-east-1.amazonaws.com | | | greengrass-fips.us-east-1.amazonaws.com | | | data.credentials.iot-fips.us-east-1.amazonaws.com | | aws.greengrass.TokenExchangeService | data.credentials.iot-fips.us-east-1.amazonaws.com | | aws.greengrass.Cli | | | aws.greengrass.StreamManager | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/FIPS.html) Stream manager does not support AWS IoT Analytics FIPS endpoint | | aws.greengrass.LogManager | logs-fips.us-east-1.amazonaws.com | | aws.greengrass.crypto.Pkcs11Provider | | | aws.greengrass.ShadowManager | | | aws.greengrass.DockerApplicationManager | ecr-fips.us-east-1.amazonaws.com | | aws.greengrass.SecretManager | secretsmanager-fips.us-east-1.amazonaws.com | | aws.greengrass.telemetry.NucleusEmitter | | | aws.greengrass.clientdevices.IPDetector | | | aws.greengrass.DiskSpooler | | # Resilience in AWS IoT Greengrass The AWS global infrastructure is built around Amazon Web Services Regions and Availability Zones. Each AWS Region provides multiple physically separated and isolated Availability Zones, which are connected with low-latency, high-throughput, and highly redundant networking. With Availability Zones, you can design and operate applications and databases that automatically fail over between zones without interruption. Availability Zones are more highly available, fault tolerant, and scalable than traditional single or multiple data center infrastructures. For more information, see [AWS Global Infrastructure](https://aws.amazon.com/about-aws/global-infrastructure/). In addition to the AWS global infrastructure, AWS IoT Greengrass offers several features to help support your data resiliency and backup needs. + You can configure a Greengrass core device to write logs to the local file system and to CloudWatch Logs. If the core device loses connectivity, it can continue to log messages on the file system. When it reconnects, it writes the log messages to CloudWatch Logs. For more information, see [Monitor AWS IoT Greengrass logs](monitor-logs.md). + If a core device loses power during a deployment, it resumes the deployment after the AWS IoT Greengrass Core software starts again. + If a core device loses internet connectivity, Greengrass client devices can continue to communicate over the local network. + You can author Greengrass components that read [stream manager](manage-data-streams.md) streams and send the data to local storage destinations. # Infrastructure security in AWS IoT Greengrass As a managed service, AWS IoT Greengrass is protected by the AWS global network security procedures that are described in the [Amazon Web Services: Overview of Security Processes](https://d0.awsstatic.com/whitepapers/Security/AWS_Security_Whitepaper.pdf) whitepaper. You use AWS published API calls to access AWS IoT Greengrass through the network. Clients must support Transport Layer Security (TLS) 1.2 or later. We recommend TLS 1.3 or later. Clients must also support cipher suites with perfect forward secrecy (PFS), such as Ephemeral Diffie-Hellman (DHE) or Elliptic Curve Ephemeral Diffie-Hellman (ECDHE). Most modern systems such as Java 7 and later support these modes. Requests must be signed by using an access key ID and a secret access key that is associated with an IAM principal. Or you can use the [AWS Security Token Service](https://docs.aws.amazon.com/STS/latest/APIReference/Welcome.html) (AWS STS) to generate temporary security credentials to sign requests. In an AWS IoT Greengrass environment, devices use X.509 certificates and cryptographic keys to connect and authenticate to the AWS Cloud. For more information, see [Device authentication and authorization for AWS IoT Greengrass](device-auth.md). # Configuration and vulnerability analysis in AWS IoT Greengrass IoT environments can consist of large numbers of devices that have diverse capabilities, are long-lived, and are geographically distributed. These characteristics make device setup complex and error-prone. And because devices are often constrained in computational power, memory, and storage capabilities, this limits the use of encryption and other forms of security on the devices themselves. Also, devices often use software with known vulnerabilities. These factors make IoT devices an attractive target for hackers and make it difficult to secure them on an ongoing basis. AWS IoT Device Defender addresses these challenges by providing tools to identify security issues and deviations from best practices. You can use AWS IoT Device Defender to analyze, audit, and monitor connected devices to detect abnormal behavior, and mitigate security risks. AWS IoT Device Defender can audit devices to ensure they adhere to security best practices and detect abnormal behavior on devices. This makes it possible to enforce consistent security policies across your devices and respond quickly when devices are compromised. IFor more information, see the following topics: + The [Device Defender component](device-defender-component.md) + [AWS IoT Device Defender](https://docs.aws.amazon.com/iot/latest/developerguide/device-defender.html) in the *AWS IoT Core Developer Guide*. In AWS IoT Greengrass environments, you should be aware of the following considerations: + It's your reponsibility to secure your physical devices, the file system on your devices, and the local network. + AWS IoT Greengrass doesn't enforce network isolation for user-defined Greengrass components, whether or not they run in a Greengrass container. Therefore, it's possible for Greengrass components to communicate with any other process running in the system or outside over network. # Code integrity in AWS IoT Greengrass V2 AWS IoT Greengrass deploys software components from the AWS Cloud to devices that run the AWS IoT Greengrass Core software. These software components include [AWS-provided components](public-components.md) and [custom components](create-components.md) that you upload to your AWS account. Every component is composed of a recipe. The recipe defines the component's metadata, and any number of artifacts, which are component binaries, such as compiled code and static resources. Component artifacts are stored in Amazon S3. As you develop and deploy Greengrass components, you follow these basic steps that work with component artifacts in your AWS account and on your devices: 1. Create and upload artifacts to S3 buckets. 1. Create a component from a recipe and artifacts in the AWS IoT Greengrass service, which calculates a [cryptographic hash](https://en.wikipedia.org/wiki/Cryptographic_hash_function) of each artifact. 1. Deploy a component to Greengrass core devices, which download and verify the integrity of each artifact. AWS is responsible for maintaining the integrity of artifacts after you upload artifacts to S3 buckets, including when you deploy components to Greengrass core devices. You are responsible for securing software artifacts before you upload the artifacts to S3 buckets. You are also responsible for securing access to resources in your AWS account, including the S3 buckets where you upload component artifacts. **Note** Amazon S3 provides a feature called S3 Object Lock that you can use to protect against changes to component artifacts in S3 buckets your AWS account. You can use S3 Object Lock to prevent component artifacts from being deleted or overwritten. For more information, see [Using S3 Object Lock](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lock.html) in the *Amazon Simple Storage Service User Guide*. When AWS publishes a public component, and when you upload a custom component, AWS IoT Greengrass calculates a cryptographic digest for each component artifact. AWS IoT Greengrass updates the component recipe to include each artifact's digest and the hash algorithm used to calculate that digest. This digest guarantees the integrity of the artifact, because if the artifact changes in the AWS Cloud or during download, its file digest won't match the digest that AWS IoT Greengrass stores in the component recipe. For more information, see [Artifacts in the component recipe reference](component-recipe-reference.md#manifest-artifacts-definition). When you deploy a component to a core device, the AWS IoT Greengrass Core software downloads the component recipe and each component artifact that the recipe defines. The AWS IoT Greengrass Core software calculates the digest of each downloaded artifact file and compares it with that artifact's digest in the recipe. If the digests don't match, the deployment fails, and the AWS IoT Greengrass Core software deletes the downloaded artifacts from the device's file system. For more information about how connections between core devices and AWS IoT Greengrass are secured, see [Encryption in transit](encryption-in-transit.md). You are responsible for securing component artifact files on your core devices' file systems. The AWS IoT Greengrass Core software saves artifacts to the `packages` folder in the Greengrass root folder. You can use AWS IoT Device Defender to analyze, audit, and monitor core devices. For more information, see [Configuration and vulnerability analysis in AWS IoT Greengrass](vulnerability-analysis-and-management.md). # AWS IoT Greengrass and interface VPC endpoints (AWS PrivateLink) You can establish a private connection between your VPC and the AWS IoT Greengrass control plane by creating an *interface VPC endpoint*. You can use this endpoint to manage components, deployments, and core devices in the AWS IoT Greengrass service. Interface endpoints are powered by [AWS PrivateLink](https://aws.amazon.com/privatelink), a technology that enables you to access AWS IoT Greengrass APIs privately without an internet gateway, NAT device, VPN connection, or AWS Direct Connect connection. Instances in your VPC don't need public IP addresses to communicate with AWS IoT Greengrass APIs. Traffic between your VPC and AWS IoT Greengrass does not leave the Amazon network. Each interface endpoint is represented by one or more [Elastic Network Interfaces](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html) in your subnets. For more information, see [Interface VPC endpoints (AWS PrivateLink)](https://docs.aws.amazon.com/vpc/latest/userguide/vpce-interface.html) in the *Amazon VPC User Guide*. **Topics** + [Considerations for AWS IoT Greengrass VPC endpoints](#vpc-endpoint-considerations) + [Create an interface VPC endpoint for AWS IoT Greengrass control plane operations](#create-vpc-endpoint-control-plane) + [Creating a VPC endpoint policy for AWS IoT Greengrass](#vpc-endpoint-policy) + [Operate an AWS IoT Greengrass core device in VPC](#vpc-operate-device-vpce) ## Considerations for AWS IoT Greengrass VPC endpoints Before you set up an interface VPC endpoint for AWS IoT Greengrass, review [Interface endpoint properties and limitations](https://docs.aws.amazon.com/vpc/latest/userguide/vpce-interface.html#vpce-interface-limitations) in the *Amazon VPC User Guide*. Additionally, be aware of the following considerations: + AWS IoT Greengrass supports making calls to all of its control plane API actions from your VPC. The control plane includes operations such as [CreateDeployment](https://docs.aws.amazon.com/greengrass/v2/APIReference/API_CreateDeployment.html) and [ListEffectiveDeployments](https://docs.aws.amazon.com/greengrass/v2/APIReference/API_ListEffectiveDeployments.html). The control plane does *not* include operations such as [ResolveComponentCandidates](device-auth.md#iot-policies) and [Discover](greengrass-discover-api.md), which are data plane operations. + VPC endpoints for AWS IoT Greengrass are currently not supported in AWS China Regions. ## Create an interface VPC endpoint for AWS IoT Greengrass control plane operations You can create a VPC endpoint for the AWS IoT Greengrass control plane using either the Amazon VPC console or the AWS Command Line Interface (AWS CLI). For more information, see [Creating an interface endpoint](https://docs.aws.amazon.com/vpc/latest/userguide/vpce-interface.html#create-interface-endpoint) in the *Amazon VPC User Guide*. Create a VPC endpoint for AWS IoT Greengrass using the following service name: + com.amazonaws.*region*.greengrass If you enable private DNS for the endpoint, you can make API requests to AWS IoT Greengrass using its default DNS name for the Region, for example, `greengrass.us-east-1.amazonaws.com`. Private DNS is enabled by default. For more information, see [Accessing a service through an interface endpoint](https://docs.aws.amazon.com/vpc/latest/userguide/vpce-interface.html#access-service-though-endpoint) in the *Amazon VPC User Guide*. ## Creating a VPC endpoint policy for AWS IoT Greengrass You can attach an endpoint policy to your VPC endpoint that controls access to AWS IoT Greengrass control plane operations. The policy specifies the following information: + The principal that can perform actions. + The actions that the principal can perform. + The resources that the principal can perform actions on. For more information, see [Controlling access to services with VPC endpoints](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-endpoints-access.html) in the *Amazon VPC User Guide*. **Example: VPC endpoint policy for AWS IoT Greengrass actions** The following is an example of an endpoint policy for AWS IoT Greengrass. When attached to an endpoint, this policy grants access to the listed AWS IoT Greengrass actions for all principals on all resources. ``` { "Statement": [ { "Principal": "*", "Effect": "Allow", "Action": [ "greengrass:CreateDeployment", "greengrass:ListEffectiveDeployments" ], "Resource": "*" } ] } ``` ## Operate an AWS IoT Greengrass core device in VPC You can operate a Greengrass core device and perform deployments in VPC without public internet access. At a minimum, you must set up the following VPC endpoints with the corresponding DNS aliases. For more information about how to create and use VPC endpoints, see [Create a VPC endpoint](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html#create-interface-endpoint-aws) in the *Amazon VPC User Guide*. **Note** The VPC feature for automatically creating a DNS record is disabled for AWS IoT data and AWS IoT Credentials. To connect these endpoints, you must manually create a Private DNS record. For more information, see [Private DNS for interface endpoints](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html#vpce-private-dns). For more information about AWS IoT Core VPC limitations, see [Limitations of VPC endpoints](https://docs.aws.amazon.com/iot/latest/developerguide/IoTCore-VPC.html#VPC-limitations). ### Prerequisites + You must install the AWS IoT Greengrass Core software using the manual provisioning steps. For more information, see [Install AWS IoT Greengrass Core software with manual resource provisioning](manual-installation.md). ### Limitations + Operating a Greengrass core device in VPC is not supported in China Regions and AWS GovCloud (US) Regions. + For more information about limitations of AWS IoT data and AWS IoT credential provider VPC endpoints, see [Limitations](https://docs.aws.amazon.com/iot/latest/developerguide/IoTCore-VPC.html#VPC-limitations). ### Set up your Greengrass core device to operate in VPC **** 1. 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" } ``` 1. Create an Amazon VPC interface for AWS IoT data and AWS IoT credentials endpoints: 1. Navigate to the [VPC](https://console.aws.amazon.com/vpc/home#/endpoints) **Endpoints** console, under **Virtual private cloud** on the left menu, choose **Endpoints** then **Create Endpoint**. 1. In the **Create endpoint** page, specify the following information. + Choose **AWS services** for **Service category**. + For **Service Name**, search by entering the keyword `iot`. In the list of `iot` services displayed, choose the endpoint. If you create a VPC endpoint for AWS IoT Core data plane, choose the AWS IoT Core data plane API endpoint for your Region. The endpoint will be of the format `com.amazonaws.region.iot.data`. If you create a VPC endpoint for AWS IoT Core credential provider, choose the AWS IoT Core credential provider endpoint for your Region. The endpoint will be of the format `com.amazonaws.region.iot.credentials`. **Note** The service name for AWS IoT Core data plane in China Region will be of the format `cn.com.amazonaws.region.iot.data`. Creating VPC endpoints for AWS IoT Core credential provider is not supported in China Region. + For **VPC** and **Subnets**, choose the VPC where you want to create the endpoint, and the Availability Zones (AZs) in which you want to create the endpoint network. + For **Enable DNS name**, make sure that **Enable for this endpoint** is not selected. Neither AWS IoT Core data plane nor AWS IoT Core credential provider supports private DNS names yet. + For **Security group**, choose the security groups you want to associate with the endpoint network interfaces. + Optionally, you can add or remove tags. Tags are name-value pairs that you use to associate with your endpoint. 1. To create your VPC endpoint, choose **Create endpoint**. 1. After you create the AWS PrivateLink endpoint, in the **Details** tab of your endpoint, you'll see a list of DNS names. You can use one of these DNS names you created in this section to [configure your private hosted zone](https://docs.aws.amazon.com/iot/latest/developerguide/IoTCore-VPC.html#connect-iot-core-create-phz-lns). 1. Create an Amazon S3 endpoint. For more information, see [Create a VPC endpoint for Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/privatelink-interface-endpoints.html#s3-creating-vpc). 1. If you are using [AWS-provided Greengrass components](https://docs.aws.amazon.com/greengrass/v2/developerguide/public-components.html), additional endpoints and configurations may be required. To view the endpoints requirements, select the component from the list of AWS-provided components and look at the Requirements section. For example, the [log manager component requirements](log-manager-component.md#log-manager-component-requirements) advise that this component must be able to perform outbound requests to the endpoint `logs.region.amazonaws.com`. If you are using your own component, you may need to review the dependencies and perform additional testing to determine if any additional endpoints are required. 1. In Greengrass nucleus configuration, `greengrassDataPlaneEndpoint` must be set to **iotdata**. For more information, see [Greengrass nucleus configuration](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration). 1. If you are in the `us-east-1` region, set the configuration parameter `s3EndpointType` to **REGIONAL** in the Greengrass nucleus configuration. This feature is available for Greengrass nucleus versions 2.11.3 or later. **Example: Component configuration** ``` { "aws.greengrass.Nucleus": { "configuration": { "awsRegion": "us-east-1", "iotCredEndpoint": "xxxxxx.credentials.iot.region.amazonaws.com", "iotDataEndpoint": "xxxxxx-ats.iot.region.amazonaws.com", "greengrassDataPlaneEndpoint": "iotdata", "s3EndpointType": "REGIONAL" ... } } } ``` The following table gives information about the corresponding custom private DNS aliases. | Service | VPC endpoint service name | VPC endpoint type | Custom private DNS alias | Notes | | --- | --- | --- | --- | --- | | AWS IoT data | `com.amazonaws.region.iot.data` | Interface | `prefix-ats.iot.region.amazonaws.com` | The private DNS record should match your account's AWS IoT data endpoint: `aws iot describe–endpoint ––endpoint–type iot:Data-ATS`. | | AWS IoT Credentials | `com.amazonaws.region.iot.credentials` | Interface | `prefix.credentials.iot.region.amazonaws.com` | The private DNS record should match your account AWS IoT Credentials endpoint: `aws iot describe–endpoint ––endpoint–type iot:CredentialProvider`. | | Amazon S3 | `com.amazonaws.region.s3` | Interface | | The DNS record is automatically created. | # Security best practices for AWS IoT Greengrass This topic contains security best practices for AWS IoT Greengrass. ## Grant minimum possible permissions Follow the principle of least privilege for your components by running them as unprivileged users. Components should not run as root unless it is absolutely necessary. You can also run the AWS IoT Greengrass Core software itself as a non-root user to further limit privileges on your device. For more information, see [Set up AWS IoT Greengrass V2 core devices as non-root](setup-greengrass-non-root.md). Use the minimum set of permissions in IAM roles. Limit the use of the `*` wildcard for the `Action` and `Resource` properties in your IAM policies. Instead, declare a finite set of actions and resources when possible. For more information about least privilege and other policy best practices, see [Policy best practices](security_iam_id-based-policy-examples.md#security_iam_service-with-iam-policy-best-practices). The least privilege best practice also applies to AWS IoT policies you attach to your Greengrass core. ## Don't hardcode credentials in Greengrass components Don't hardcode credentials in your user-defined Greengrass components. To better protect your credentials: + To interact with AWS services, define permissions for specific actions and resources in the [Greengrass core device service role](device-service-role.md). + Use the [secret manager component](secret-manager-component.md) to store your credentials. Or, if the function uses the AWS SDK, use credentials from the default credential provider chain. ## Don't log sensitive information You should prevent the logging of credentials and other personally identifiable information (PII). We recommend that you implement the following safeguards even though access to local logs on a core device requires root privileges and access to CloudWatch Logs requires IAM permissions. + Don't use sensitive information in MQTT topic paths. + Don't use sensitive information in device (thing) names, types, and attributes in the AWS IoT Core registry. + Don't log sensitive information in your user-defined Greengrass components or Lambda functions. + Don't use sensitive information in the names and IDs of Greengrass resources: + Core devices + Components + Deployments + Loggers ## Keep your device clock in sync It's important to have an accurate time on your device. X.509 certificates have an expiry date and time. The clock on your device is used to verify that a server certificate is still valid. Device clocks can drift over time or batteries can get discharged. For more information, see the [ Keep your device's clock in sync](https://docs.aws.amazon.com/iot/latest/developerguide/security-best-practices.html#device-clock) best practice in the *AWS IoT Core Developer Guide*. ## Cipher Suite Recommendations Greengrass default selects the latest TLS Cipher Suites available on the device. Consider disabling the use of legacy cipher suites on the device. For example, CBC cipher suites. For more information, see the [Java Cryptography Configuration](https://www.java.com/configure_crypto.html). ## See also + [Security best practices in AWS IoT Core](https://docs.aws.amazon.com/iot/latest/developerguide/security-best-practices.html) in the *AWS IoT Developer Guide* + [ Ten security golden rules for Industrial IoT solutions](https://aws.amazon.com/blogs/iot/ten-security-golden-rules-for-industrial-iot-solutions/) on the *Internet of Things on AWS Official Blog* # Run AWS IoT Greengrass V2 as a non-root user Typically, the root user installs and runs the AWS IoT Greengrass Core software on Linux devices. To increase device security, you can set up a non-root user to run the AWS IoT Greengrass Core software instead. This section provides guidance on setting up non-root configurations. If you are setting up new AWS IoT Greengrass V2 core devices and want to run them as a non-root user from the start, see [Set up AWS IoT Greengrass V2 core devices as non-root](setup-greengrass-non-root.md). This guide covers multiple solutions based on your device constraints and security requirements. **Note** The non-root configurations in this section apply to Linux devices only. On Windows, AWS IoT Greengrass must run as a system service. **Topics** + [Set up AWS IoT Greengrass V2 core devices as non-root](setup-greengrass-non-root.md) # Set up AWS IoT Greengrass V2 core devices as non-root This page presents four solutions for running the AWS IoT Greengrass Core software as non-root. Review the comparison table to understand the features and tradeoffs of each solution, then use the decision flowchart to identify which one fits your requirements. **Note** The non-root solutions on this page apply to the AWS IoT Greengrass nucleus on Linux devices only. Windows is not included because AWS IoT Greengrass V2 must run as a system service on Windows. For standard root installation on Linux, see [Install AWS IoT Greengrass Core software with automatic resource provisioning](quick-installation.md). To run AWS IoT Greengrass nucleus lite as a non-root user, see [Using Podman](https://github.com/aws-greengrass/aws-greengrass-lite/blob/main/docs/BUILD.md#optional-using-podman) in the AWS IoT Greengrass nucleus lite GitHub repository. **Topics** + [Choose a non-root solution](#non-root-choose-solution) + [Solution 1: Set up AWS IoT Greengrass V2 without root access](#non-root-solution-1) + [Solution 2: Set up AWS IoT Greengrass V2 as non-root without component user separation](#non-root-solution-2) + [Solution 3: Set up AWS IoT Greengrass V2 as non-root with component user separation](#non-root-solution-3) + [Solution 4: Set up AWS IoT Greengrass V2 as root with limited capabilities](#non-root-solution-4) + [Linux capabilities required by AWS IoT Greengrass V2](#linux-capabilities-reference) ## Choose a non-root solution Use the following table to compare the non-root solutions and understand their tradeoffs. Each solution offers different capabilities depending on your security requirements and device constraints. **Non-root solutions** | Solution | Requires root access | Can run components as different users | Runs Greengrass as system service | Best for | | --- | --- | --- | --- | --- | | [Solution 1: No root access](#non-root-solution-1) | No | No | No (user service optional) | Devices where you don't have root access | | [Solution 2: Non-root, single user](#non-root-solution-2) | Yes (setup only) | No | Yes | Running Greengrass as a non-root user with all components running as the same user | | [Solution 3: Non-root, multi-user](#non-root-solution-3) | Yes (setup only) | Yes | Yes | Running Greengrass as a non-root user while running components as different users | | [Solution 4: Root with limited capabilities](#non-root-solution-4) | Yes | Yes | Yes | Running Greengrass as root with a limited set of Linux capabilities | The following flowchart guides you through selecting the appropriate solution based on your device constraints and requirements. ![\[Flowchart showing decision process for choosing a non-root solution. Start by asking if you have root access on your core device. If no, use Solution 1. If yes, ask if you need to run components as different Linux users. If no, use Solution 2. If yes, ask if you want Greengrass to run as root user with limited capabilities. If yes, use Solution 4. If no, use Solution 3.\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/images/non-root-solution-decision-flow.png) ## Solution 1: Set up AWS IoT Greengrass V2 without root access Use this solution when you don't have root access on the device. In this configuration, the AWS IoT Greengrass Core software runs entirely as a non-root user without elevated privileges. **Tradeoffs** This solution has the following limitations: + **No component user separation** – All components run as the same user that runs the AWS IoT Greengrass Core software. You cannot use the `posixUser` configuration to run components as different users. + **RequiresPrivilege ignored** – The AWS IoT Greengrass Core software ignores the `RequiresPrivilege` option in component recipes. Components cannot request elevated privileges. + **No system service** – You cannot install the AWS IoT Greengrass Core software as a system service. You can optionally configure AWS IoT Greengrass V2 to run as a systemd user service. **Prerequisites** This solution requires: + A non-root user account on the device + Write access to the directory where you want to install the AWS IoT Greengrass Core software **To install and run AWS IoT Greengrass V2 without root access** 1. Complete the following steps from [Install AWS IoT Greengrass Core software with automatic resource provisioning](quick-installation.md): set up your device environment, provide credentials, and download the AWS IoT Greengrass Core software. 1. Create the installation directory and ensure your user owns it. ``` mkdir -p $HOME/greengrass/v2 ``` 1. Run the installer without `sudo`. Set `--component-default-user` to your current user. ``` java -Droot="$HOME/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 $USER \ --provision true ``` Do not use `--setup-system-service true` because you don't have root access to create a system service. **(Optional) Set up a systemd user service** You can configure a systemd user service to manage the AWS IoT Greengrass Core software. This allows the software to start automatically when you log in. **To set up a systemd user service** 1. Stop the AWS IoT Greengrass Core software if it is currently running. ``` kill $(cat $HOME/greengrass/v2/alts/loader.pid) ``` 1. Create the systemd user service directory. ``` mkdir -p $HOME/.config/systemd/user ``` 1. Create the service file at `$HOME/.config/systemd/user/greengrass.service` with the following content. ``` [Unit] Description=Greengrass Core [Service] Type=simple PIDFile=%h/greengrass/v2/alts/loader.pid RemainAfterExit=no Restart=on-failure RestartSec=10 ExecStart=/bin/sh %h/greengrass/v2/alts/current/distro/bin/loader Environment="JAVA_HOME=/path/to/java" [Install] WantedBy=default.target ``` In systemd user unit files, `%h` is a specifier that resolves to the home directory of the user running the service. Replace */path/to/java* with the path to your Java installation. 1. Enable and start the service. ``` systemctl --user daemon-reload systemctl --user enable greengrass.service systemctl --user start greengrass.service ``` **Restart and OTA update behavior** The behavior depends on whether you configured a systemd user service. With a user service + **Device reboot** – The AWS IoT Greengrass Core software starts automatically when the user logs in. + **OTA update** – OTA updates succeed and the software restarts automatically. Without a user service + **Device reboot** – The AWS IoT Greengrass Core software does not restart automatically. You must manually start it. + **OTA update** – OTA updates succeed, but you must manually start the AWS IoT Greengrass Core software afterward. **System resource limits** Per-component resource limits using cgroups do not work in this solution because non-root users cannot create cgroup directories in `/sys/fs/cgroup/`. If you deploy a component with resource limits configured, the AWS IoT Greengrass Core software ignores the configured limits. You can use the following alternatives to manage resource usage: + **Systemd user service limits** – If you run the AWS IoT Greengrass Core software as a systemd user service, you can add resource limits to the service file at `$HOME/.config/systemd/user/greengrass.service`. These limits apply to the entire service, including the Greengrass nucleus and all components. ``` MemoryMax=2G CPUQuota=100% ``` + **Greengrass nucleus JVM limits** – You can limit the Greengrass nucleus process memory by configuring JVM options. For more information, see [Configure the AWS IoT Greengrass Core software](configure-greengrass-core-v2.md). ## Solution 2: Set up AWS IoT Greengrass V2 as non-root without component user separation Use this solution when you have root access for initial setup and want the AWS IoT Greengrass Core software to run as a non-root system service, but you don't need to run components as different users. This is similar to Solution 1, but the software runs as a system service that starts automatically on boot. **Tradeoffs** This solution has the following limitations: + **No component user separation** – All components run as the same user that runs the AWS IoT Greengrass Core software. You cannot use the `posixUser` configuration to run components as different users. + **RequiresPrivilege ignored** – The AWS IoT Greengrass Core software ignores the `RequiresPrivilege` option in component recipes. Components cannot request elevated privileges. **Prerequisites** This solution requires: + Root access for initial setup + systemd on your device **To install and run AWS IoT Greengrass V2 as non-root without component user separation** 1. Complete the following steps from [Install AWS IoT Greengrass Core software with automatic resource provisioning](quick-installation.md): set up your device environment, provide credentials, and download the AWS IoT Greengrass Core software. 1. Create a non-root user that will run the AWS IoT Greengrass Core software and all components. ``` sudo useradd --create-home gg_non_root ``` 1. Log in as the non-root user and run the installer. Set `--component-default-user` to the same user. Do not use `sudo` and do not set up a system service. ``` java -Droot="/home/gg_non_root/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 gg_non_root \ --provision true \ --setup-system-service false ``` 1. As root, create the system service file at `/etc/systemd/system/greengrass.service` with the following content. ``` [Unit] Description=Greengrass Core After=network.target [Service] Type=simple User=gg_non_root PIDFile=/home/gg_non_root/greengrass/v2/alts/loader.pid RemainAfterExit=no Restart=on-failure RestartSec=10 ExecStart=/bin/sh -c "exec /home/gg_non_root/greengrass/v2/alts/current/distro/bin/loader >> /home/gg_non_root/greengrass/v2/logs/loader.log 2>&1" KillMode=mixed NoNewPrivileges=true ProtectSystem=strict ReadWritePaths=/home/gg_non_root/greengrass /tmp [Install] WantedBy=multi-user.target ``` 1. Stop the running AWS IoT Greengrass Core instance, then enable and start the system service. ``` sudo systemctl daemon-reload sudo systemctl enable greengrass.service sudo systemctl start greengrass.service ``` **Restart and OTA update behavior** In this solution: + The AWS IoT Greengrass Core software runs as a system service and restarts automatically on failure or device reboot. + OTA updates to the AWS IoT Greengrass Core software work. The service restarts automatically as the configured non-root user. **System resource limits** Per-component resource limits using cgroups do not work in this solution because non-root users without Linux capabilities cannot create cgroup directories in `/sys/fs/cgroup/`. If you deploy a component with resource limits configured, the AWS IoT Greengrass Core software ignores the configured limits. You can use the following alternatives to manage resource usage: + **Systemd service limits** – You can add resource limits to the system service file at `/etc/systemd/system/greengrass.service`. These limits apply to the entire service, including the Greengrass nucleus and all components. ``` MemoryMax=2G CPUQuota=100% ``` + **Greengrass nucleus JVM limits** – You can limit the Greengrass nucleus process memory by configuring JVM options. For more information, see [Configure the AWS IoT Greengrass Core software](configure-greengrass-core-v2.md). ## Solution 3: Set up AWS IoT Greengrass V2 as non-root with component user separation Use this solution when you have root access for initial setup but want the AWS IoT Greengrass Core software to run as a non-root user while maintaining the ability to run components as different users. This configuration uses Linux capabilities and sudoers to allow the non-root user to switch to other users when running components. **Tradeoffs** This solution has the following limitations: + **Requires sudoers configuration** – You must configure sudoers to allow the AWS IoT Greengrass V2 user to run commands as other users. **Prerequisites** This solution requires: + Root access for initial setup + systemd version 229 or later, which supports `AmbientCapabilities`. To check your version, run `systemctl --version`. **To install and run AWS IoT Greengrass V2 as non-root with component user separation** 1. Complete the following steps from [Install AWS IoT Greengrass Core software with automatic resource provisioning](quick-installation.md): set up your device environment, provide credentials, and download the AWS IoT Greengrass Core software. 1. Create a non-root user that will run the AWS IoT Greengrass Core software. ``` sudo useradd --create-home gg_non_root ``` 1. Add the non-root user to sudoers so that it can run commands as the component user. Create a file at `/etc/sudoers.d/gg_non_root`. ``` gg_non_root ALL=(ggc_user:ggc_group) NOPASSWD: SETENV: /bin/sh, /bin/bash ``` If you configure components to run as additional users with `posixUser`, add a sudoers entry for each user. For example: ``` gg_non_root ALL=(ggc_user:ggc_group) NOPASSWD: SETENV: /bin/sh, /bin/bash gg_non_root ALL=(another_user:another_group) NOPASSWD: SETENV: /bin/sh, /bin/bash ``` 1. Log in as the non-root user and run the installer. Do not use `sudo` and do not set up a system service. ``` java -Droot="/home/gg_non_root/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 false ``` 1. As root, create the system service file at `/etc/systemd/system/greengrass.service` with the following content. ``` [Unit] Description=Greengrass Core After=network.target [Service] Type=simple User=gg_non_root PIDFile=/home/gg_non_root/greengrass/v2/alts/loader.pid RemainAfterExit=no Restart=on-failure RestartSec=10 ExecStart=/bin/sh -c "exec /home/gg_non_root/greengrass/v2/alts/current/distro/bin/loader >> /home/gg_non_root/greengrass/v2/logs/loader.log 2>&1" KillMode=mixed AmbientCapabilities=CAP_CHOWN CAP_DAC_OVERRIDE CAP_DAC_READ_SEARCH CAP_FOWNER CAP_SETUID CAP_SETGID CAP_SYS_RESOURCE CAP_AUDIT_WRITE CapabilityBoundingSet=CAP_CHOWN CAP_DAC_OVERRIDE CAP_DAC_READ_SEARCH CAP_FOWNER CAP_SETUID CAP_SETGID CAP_SYS_RESOURCE CAP_AUDIT_WRITE ProtectSystem=strict ReadWritePaths=/home/gg_non_root/greengrass /tmp [Install] WantedBy=multi-user.target ``` For information about the required capabilities, see [Linux capabilities required by AWS IoT Greengrass V2](#linux-capabilities-reference). + `AmbientCapabilities` grants the specified Linux capabilities to the non-root user running the service. This allows the AWS IoT Greengrass Core software to perform privileged operations such as switching users when running components, without running as root. + `CapabilityBoundingSet` limits the maximum set of capabilities that the service and its child processes can use. Capabilities not in this set are permanently dropped. + `ProtectSystem=strict` makes the entire file system read-only for the service, preventing modification of the operating system. + `ReadWritePaths` specifies the only directories that the service can write to. 1. Stop the running AWS IoT Greengrass Core instance, then enable and start the system service. ``` sudo systemctl daemon-reload sudo systemctl enable greengrass.service sudo systemctl start greengrass.service ``` **Restart and OTA update behavior** In this solution: + The AWS IoT Greengrass Core software runs as a system service and restarts automatically on failure or device reboot. + OTA updates to the AWS IoT Greengrass Core software work. The service restarts automatically as the configured non-root user. **System resource limits** Per-component resource limits for memory and CPU work in this solution the same way as when running the AWS IoT Greengrass Core software as root. ## Solution 4: Set up AWS IoT Greengrass V2 as root with limited capabilities Use this solution when you want the AWS IoT Greengrass Core software to run as root but with a reduced set of Linux capabilities. This configuration provides the full functionality of running as root while limiting the attack surface by restricting the capabilities available to the software and its components. **Tradeoffs** This solution has the following considerations: + **Components with RequiresPrivilege have limited capabilities** – Components that use `RequiresPrivilege` run with the same limited set of capabilities as the AWS IoT Greengrass Core software, not full root privileges. **Prerequisites** This solution requires: + Root access + systemd on your device **To install and run AWS IoT Greengrass V2 as root with limited capabilities** 1. Complete the following steps from [Install AWS IoT Greengrass Core software with automatic resource provisioning](quick-installation.md): set up your device environment, provide credentials, and download the AWS IoT Greengrass Core software. 1. Modify the service template file at `GreengrassInstaller/bin/greengrass.service.template`, in the directory where you downloaded the AWS IoT Greengrass Core software. Add the following lines to the `[Service]` section before you run the installer: ``` CapabilityBoundingSet=CAP_CHOWN CAP_DAC_OVERRIDE CAP_DAC_READ_SEARCH CAP_FOWNER CAP_SETUID CAP_SETGID CAP_SYS_RESOURCE CAP_AUDIT_WRITE ProtectSystem=strict ReadWritePaths=/greengrass /tmp ``` + `CapabilityBoundingSet` is a systemd security feature that limits the Linux capabilities available to the AWS IoT Greengrass Core software and all of its child processes. By configuring a bounding set, you restrict what the Greengrass nucleus process and components can do, even when running as root. For information about each capability, see [Linux capabilities required by AWS IoT Greengrass V2](#linux-capabilities-reference). + `ProtectSystem=strict` makes the entire file system read-only for the service, preventing modification of the operating system. This provides systemd sandboxing that protects system files even if a malicious component runs with elevated privileges. + `ReadWritePaths` specifies the only directories that the service can write to. Together with `ProtectSystem=strict`, this limits the service to writing only to the AWS IoT Greengrass V2 root directory and `/tmp`. 1. Run the installer with `--setup-system-service true`. ``` 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 ``` **Restart and OTA update behavior** In this solution: + The AWS IoT Greengrass Core software runs as a system service and restarts automatically on failure or device reboot. + OTA updates to the AWS IoT Greengrass Core software work. The software updates and restarts automatically. **System resource limits** Per-component resource limits for memory and CPU work in this solution the same way as when running the AWS IoT Greengrass Core software as root. ## Linux capabilities required by AWS IoT Greengrass V2 The following table describes the Linux capabilities required by the AWS IoT Greengrass Core software when running in non-root configurations. These capabilities are used in Solutions 3 and 4. **Required Linux capabilities** | Capability | Description | Required for | | --- | --- | --- | | `CAP_CHOWN` | Make arbitrary changes to file UIDs and GIDs | Changing file ownership depending on the user executing the component | | `CAP_DAC_OVERRIDE` | Bypass file read, write, and execute permission checks | Allowing the Greengrass nucleus user to execute files when used for scripts with `RequiresPrivilege` | | `CAP_DAC_READ_SEARCH` | Bypass file read permission checks and directory read and execute permission checks | Walking the folder hierarchy even for folders the Greengrass nucleus user does not have permission to read | | `CAP_FOWNER` | Bypass permission checks on operations that normally require the filesystem UID of the process to match the UID of the file | Bypassing file ownership checks | | `CAP_SETUID` | Make arbitrary manipulations of process UIDs | Using `sudo` when executing scripts as a different user than the user running the Greengrass nucleus | | `CAP_SETGID` | Make arbitrary manipulations of process GIDs | Using `sudo` when executing scripts as a different group than the group running the Greengrass nucleus | | `CAP_SYS_RESOURCE` | Override resource limits | Setting resource limits on component processes, even if limits are not specified in deployments | | `CAP_AUDIT_WRITE` | Write records to kernel auditing log | Allowing `sudo` to write to the kernel audit log |