# Configure IDT settings to run the Amazon IoT Greengrass qualification suite Before you run tests, you must configure settings for Amazon credentials and devices on your host computer. ## Configure Amazon credentials in config.json You must configure your IAM user credentials in the `/configs/config.json` file. Use the credentials for the IDT for Amazon IoT Greengrass V2 user created in [Create and configure an Amazon Web Services account](dev-tst-prereqs.md#config-aws-account-for-idt). You can specify your credentials in one of two ways: + In a credentials file + As environment variables ### Configure Amazon credentials with a credentials file IDT uses the same credentials file as the Amazon CLI. For more information, see [Configuration and credential files](https://docs.amazonaws.cn/cli/latest/userguide/cli-config-files.html). The location of the credentials file varies, depending on the operating system you are using: + macOS, Linux: `~/.aws/credentials` + Windows: `C:\Users\UserName\.aws\credentials` Add your Amazon credentials to the `credentials` file in the following format: ``` [default] aws_access_key_id = aws_secret_access_key = ``` To configure IDT for Amazon IoT Greengrass V2 to use Amazon credentials from your `credentials` file, edit your `config.json` file as follows: ``` { "awsRegion": "region", "auth": { "method": "file", "credentials": { "profile": "default" } } } ``` **Note** If you do not use the `default` Amazon profile, be sure to change the profile name in your `config.json` file. For more information, see [Named profiles](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html). ### Configure Amazon credentials with environment variables Environment variables are variables maintained by the operating system and used by system commands. They are not saved if you close the SSH session. IDT for Amazon IoT Greengrass V2 can use the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables to store your Amazon credentials. To set these variables on Linux, macOS, or Unix, use **export**: ``` export AWS_ACCESS_KEY_ID= export AWS_SECRET_ACCESS_KEY= ``` To set these variables on Windows, use **set**: ``` set AWS_ACCESS_KEY_ID= set AWS_SECRET_ACCESS_KEY= ``` To configure IDT to use the environment variables, edit the `auth` section in your `config.json` file. Here is an example: ``` { "awsRegion": "region", "auth": { "method": "environment" } } ``` ## Configure device.json **Note** IDT v4.9.3 supports testing the `ml`, `docker`, and `streamManagement` features. IDT v4.9.4 and later versions support testing `docker`. If you don't want to test these features, set the corresponding value to `no`. In addition to Amazon credentials, IDT for Amazon IoT Greengrass V2 needs information about the devices that tests are run on. Example information would be IP address, login information, operating system, and CPU architecture. You must provide this information using the `device.json` template located in ` /configs/device.json`: ------ #### [ IDT v4.9.3 ] ``` [ { "id": "", "sku": "", "features": [ { "name": "arch", "value": "x86_64 | armv6l | armv7l | aarch64" }, { "name": "ml", "value": "dlr | tensorflowlite | dlr,tensorflowlite | no" }, { "name": "docker", "value": "yes | no" }, { "name": "streamManagement", "value": "yes | no" }, { "name": "hsi", "value": "hsm | no" } ], "devices": [ { "id": "", "operatingSystem": "Linux | Windows", "connectivity": { "protocol": "ssh", "ip": "", "port": 22, "publicKeyPath": "", "auth": { "method": "pki | password", "credentials": { "user": "", "privKeyPath": "/path/to/private/key", "password": "" } } } } ] } ] ``` **Note** Specify `privKeyPath` only if `method` is set to `pki`. Specify `password` only if `method` is set to `password`. All properties that contain values are required, as described here: `id` A user-defined alphanumeric ID that uniquely identifies a collection of devices called a *device pool*. Devices that belong to a pool must have identical hardware. When you run a suite of tests, devices in the pool are used to parallelize the workload. Multiple devices are used to run different tests. `sku` An alphanumeric value that uniquely identifies the device under test. The SKU is used to track qualified boards. If you want to list your device in the Amazon Partner Device Catalog, the SKU you specify here must match the SKU that you use in the listing process. `features` An array that contains the device's supported features. All features are required. `arch` The supported operating system architectures that the test run validates. Valid values are: + `x86_64` + `armv6l` + `armv7l` + `aarch64` `ml` Validates that the device meets all of the required technical dependencies to use the Amazon-provided machine learning (ML) components. Enabling this feature also validates that the device can perform ML inference using the [Deep Learning Runtime](https://github.com/neo-ai/neo-ai-dlr) and [TensorFlow Lite](https://www.tensorflow.org/lite/guide/python) ML frameworks. . Valid values are any combination of `dlr` and `tensorflowlite`, or `no`. `docker` Validates that the device meets all required technical dependencies to use the Amazon-provided Docker application manager (`aws.greengrass.DockerApplicationManager`) component. Enabling this feature also validates that the device can download a Docker container image from Amazon ECR . . Valid values are any combination of `yes` or `no`. `streamManagement` Validates that the device can download, install, and run the [Amazon IoT Greengrass stream manager](manage-data-streams.md). Valid values are any combination of `yes` or `no`. `hsi` Validates that the device can authenticate connections to the Amazon IoT and Amazon IoT Greengrass services using a private key and certificate that are stored in a hardware security module (HSM). This test also verifies that the Amazon-provided [PKCS\$111 provider component](pkcs11-provider-component.md) can interface with the HSM using a vendor-provided PKCS\$111 library. For more information, see [Hardware security integration](hardware-security.md). Valid values are `hsm` or `no`. Testing the `hsi` is available only with IDT v4.9.3 and later versions. `devices.id` A user-defined unique identifier for the device being tested. `devices.operatingSystem` The device operating system. Supported values are `Linux` and `Windows`. `connectivity.protocol` The communication protocol used to communicate with this device. Currently, the only supported value is `ssh` for physical devices. `connectivity.ip` The IP address of the device being tested. This property applies only if `connectivity.protocol` is set to `ssh`. `connectivity.port` Optional. The port number to use for SSH connections. The default value is 22. This property applies only if `connectivity.protocol` is set to `ssh`. `connectivity.publicKeyPath` Optional. The full path to the public key used to authenticate connections to the device under test. When you specify the `publicKeyPath`, IDT validates the device’s public key when it establishes an SSH connection to the device under test. If this value is not specified, IDT creates an SSH connection, but doesn’t validate the device’s public key. We strongly recommend that you specify the path to the public key, and that you use a secure method to fetch this public key. For standard command line-based SSH clients, the public key is provided in the `known_hosts` file. If you specify a separate public key file, this file must use the same format as the `known_hosts` file, that is, ` ip-address key-type public-key`. If there are multiple entries with the same ip-address, the entry for the key-type used by IDT must be before the other entries in the file. `connectivity.auth` Authentication information for the connection. This property applies only if `connectivity.protocol` is set to `ssh`. `connectivity.auth.method` The authentication method used to access a device over the given connectivity protocol. Supported values are: + `pki` + `password` `connectivity.auth.credentials` The credentials used for authentication. `connectivity.auth.credentials.password` The password used for signing in to the device being tested. This value applies only if `connectivity.auth.method` is set to `password`. `connectivity.auth.credentials.privKeyPath` The full path to the private key used to sign in to the device under test. This value applies only if `connectivity.auth.method` is set to `pki`. `connectivity.auth.credentials.user` The user name for signing in to the device being tested. ------ #### [ IDT v4.9.4 ] ``` [ { "id": "", "sku": "", "features": [ { "name": "arch", "value": "x86_64 | armv6l | armv7l | aarch64" }, { "name": "docker", "value": "yes | no" }, { "name": "hsi", "value": "hsm | no" } ], "devices": [ { "id": "", "operatingSystem": "Linux | Windows", "connectivity": { "protocol": "ssh", "ip": "", "port": 22, "publicKeyPath": "", "auth": { "method": "pki | password", "credentials": { "user": "", "privKeyPath": "/path/to/private/key", "password": "" } } } } ] } ] ``` **Note** Specify `privKeyPath` only if `method` is set to `pki`. Specify `password` only if `method` is set to `password`. All properties that contain values are required, as described here: `id` A user-defined alphanumeric ID that uniquely identifies a collection of devices called a *device pool*. Devices that belong to a pool must have identical hardware. When you run a suite of tests, devices in the pool are used to parallelize the workload. Multiple devices are used to run different tests. `sku` An alphanumeric value that uniquely identifies the device under test. The SKU is used to track qualified boards. If you want to list your device in the Amazon Partner Device Catalog, the SKU you specify here must match the SKU that you use in the listing process. `features` An array that contains the device's supported features. All features are required. `arch` The supported operating system architectures that the test run validates. Valid values are: + `x86_64` + `armv6l` + `armv7l` + `aarch64` `docker` Validates that the device meets all required technical dependencies to use the Amazon-provided Docker application manager (`aws.greengrass.DockerApplicationManager`) component. Enabling this feature also validates that the device can download a Docker container image from Amazon ECR . . Valid values are any combination of `yes` or `no`. `hsi` Validates that the device can authenticate connections to the Amazon IoT and Amazon IoT Greengrass services using a private key and certificate that are stored in a hardware security module (HSM). This test also verifies that the Amazon-provided [PKCS\$111 provider component](pkcs11-provider-component.md) can interface with the HSM using a vendor-provided PKCS\$111 library. For more information, see [Hardware security integration](hardware-security.md). Valid values are `hsm` or `no`. Testing the `hsi` is available only with IDT v4.9.3 and later versions. `devices.id` A user-defined unique identifier for the device being tested. `devices.operatingSystem` The device operating system. Supported values are `Linux` and `Windows`. `connectivity.protocol` The communication protocol used to communicate with this device. Currently, the only supported value is `ssh` for physical devices. `connectivity.ip` The IP address of the device being tested. This property applies only if `connectivity.protocol` is set to `ssh`. `connectivity.port` Optional. The port number to use for SSH connections. The default value is 22. This property applies only if `connectivity.protocol` is set to `ssh`. `connectivity.publicKeyPath` Optional. The full path to the public key used to authenticate connections to the device under test. When you specify the `publicKeyPath`, IDT validates the device’s public key when it establishes an SSH connection to the device under test. If this value is not specified, IDT creates an SSH connection, but doesn’t validate the device’s public key. We strongly recommend that you specify the path to the public key, and that you use a secure method to fetch this public key. For standard command line-based SSH clients, the public key is provided in the `known_hosts` file. If you specify a separate public key file, this file must use the same format as the `known_hosts` file, that is, ` ip-address key-type public-key`. If there are multiple entries with the same ip-address, the entry for the key-type used by IDT must be before the other entries in the file. `connectivity.auth` Authentication information for the connection. This property applies only if `connectivity.protocol` is set to `ssh`. `connectivity.auth.method` The authentication method used to access a device over the given connectivity protocol. Supported values are: + `pki` + `password` `connectivity.auth.credentials` The credentials used for authentication. `connectivity.auth.credentials.password` The password used for signing in to the device being tested. This value applies only if `connectivity.auth.method` is set to `password`. `connectivity.auth.credentials.privKeyPath` The full path to the private key used to sign in to the device under test. This value applies only if `connectivity.auth.method` is set to `pki`. `connectivity.auth.credentials.user` The user name for signing in to the device being tested. ------ ## Configure userdata.json IDT for Amazon IoT Greengrass V2 also needs additional information about the location of test artifacts and Amazon IoT Greengrass software. You must provide this information using the `userdata.json` template located in ` /configs/userdata.json`: ``` { "TempResourcesDirOnDevice": "/path/to/temp/folder", "InstallationDirRootOnDevice": "/path/to/installation/folder", "GreengrassNucleusZip": "/path/to/aws.greengrass.nucleus.zip", "PreInstalled": "yes/no", "GreengrassV2TokenExchangeRole": "custom-iam-role-name", "hsm": { "greengrassPkcsPluginJar": "/path/to/aws.greengrass.crypto.Pkcs11Provider-latest.jar", "pkcs11ProviderLibrary": "/path/to/pkcs11-vendor-library", "slotId": "slot-id", "slotLabel": "slot-label", "slotUserPin": "slot-pin", "keyLabel": "key-label", "preloadedCertificateArn": "certificate-arn" "rootCA": "path/to/root-ca" } } ``` All properties that contain values are required as described here: `TempResourcesDirOnDevice` The full path to a temporary folder on the device under test in which to store test artifacts. Make sure that sudo permissions are not required to write to this directory. IDT deletes the contents of this folder when it finishes running a test. `InstallationDirRootOnDevice` The full path to a folder on the device in which to install Amazon IoT Greengrass. For PreInstalled Greengrass, this is the path to the Greengrass installation directory. You must set the required file permissions for this folder. Run the following command for each folder in the installation path. ``` sudo chmod 755 folder-name ``` `GreengrassNucleusZip` The full path to the Greengrass nucleus ZIP (`greengrass-nucleus-latest.zip`) file on your host computer. This field is not required for testing with PreInstalled Greengrass. For information about the supported versions of the Greengrass nucleus for IDT for Amazon IoT Greengrass, see [Latest IDT version for Amazon IoT Greengrass V2](dev-test-versions.md#idt-latest-version). To download the latest Greengrass software, see [Download the Amazon IoT Greengrass software](https://docs.amazonaws.cn/greengrass/v2/developerguide/dev-tst-prereqs.html#config-gg). `PreInstalled` This feature is available for IDT v4.5.8 and later versions on Linux devices only. (Optional) When the value is *yes*, IDT will assume the path mentioned in `InstallationDirRootOnDevice` to be the directory where Greengrass is installed. For more information about how to install Greengrass on your device, see [Install Amazon IoT Greengrass Core software with automatic resource provisioning](quick-installation.md). If [installing with manual provisioning](https://docs.amazonaws.cn/greengrass/v2/developerguide/manual-installation.html), include the “Add the Amazon IoT thing to a new or existing thing group” step when creating an [Amazon IoT thing](https://docs.amazonaws.cn/greengrass/v2/developerguide/manual-installation.html#create-iot-thing) manually. IDT assumes that the thing and thing group are created during installation setup. Make sure that these values are reflected in the `effectiveConfig.yaml` file. IDT checks for the file `effectiveConfig.yaml` under `/config/effectiveConfig.yaml`. For running tests with HSM, make sure that the `aws.greengrass.crypto.Pkcs11Provider` field is updated in `effectiveConfig.yaml`. `GreengrassV2TokenExchangeRole` (Optional) The custom IAM role that you want to use as the token exchange role that the device under test assumes to interact with Amazon resources. IDT uses this custom IAM role instead of creating the default token exchange role during the test run. If you use a custom role, you can update the [IAM permissions for the test user](dev-tst-prereqs.md#configure-idt-permissions) to exclude the `iamResourcesUpdate` statement that allows the user to create and delete IAM roles and policies. For more information about creating a custom IAM role as your token exchange role, see [Configure a custom token exchange role](device-config-setup.md#configure-custom-tes-role-for-idt). `hsm` This feature is available for IDT v4.5.1 and later. (Optional) The configuration information for testing with an Amazon IoT Greengrass Hardware Security Module (HSM). Otherwise, the `hsm` property should be omitted. For more information, see [Hardware security integration](hardware-security.md). This property applies only if `connectivity.protocol` is set to `ssh`. The HSM configuration may be considered sensitive data if the hardware security module is shared between IDT and another system. In this situation, you may avoid securing these configuration values in plaintext by storing them in an Amazon Parameter Store SecureString parameter and configuring IDT to fetch them during test execution. For more information, see [Fetch configuration from Amazon Parameter Store](#fetch-config) `hsm.greengrassPkcsPluginJar` The full path to the [PKCS\$111 provider component](pkcs11-provider-component.md) that you download to the IDT host machine. Amazon IoT Greengrass provides this component as JAR file that you can download to specify as a provisioning plugin during installation. You can download the latest version of the component's JAR file as the following URL: [https://d2s8p88vqu9w66.cloudfront.net/releases/Pkcs11Provider/aws.greengrass.crypto.Pkcs11Provider-latest.jar](https://d2s8p88vqu9w66.cloudfront.net/releases/Pkcs11Provider/aws.greengrass.crypto.Pkcs11Provider-latest.jar). `hsm.pkcs11ProviderLibrary` The full path to the PKCS\$111 library that is provided by the hardware security module (HSM) vendor to interact with the HSM. `hsm.slotId` The slot ID that is used to identify the HSM slot to which you load the key and certificate. `hsm.slotLabel` The slot label that is used to identify the HSM slot to which you load the key and certificate. `hsm.slotUserPin` The user PIN that IDT uses to authenticate Amazon IoT Greengrass Core software to the HSM. As a security best practice, don't use the same user PIN on production devices. `hsm.keyLabel` The label used to identify the key in the hardware module. Both the key and the certificate must use the same key label. `hsm.preloadedCertificateArn` The Amazon Resource Name (ARN) of the uploaded device certificate in the Amazon IoT cloud. You must have previously generated this certificate using the key in the HSM, imported it into your HSM, and uploaded it to the Amazon IoT cloud. For information about generating and importing the certificate, see the documentation for your HSM. You must upload the certificate to the same account and Region that you provide in [config.json.](#cfg-aws-gg). For more information about uploading your certificate to Amazon IoT, see [Register a client certificate manually](https://docs.amazonaws.cn/iot/latest/developerguide/manual-cert-registration.html) in the *Amazon IoT Developer Guide*. `hsm.rootCAPath` (Optional) The full path on the IDT host machine to the root certificate authority (CA) that signed your certificate. This is required if the certificate in your HSM created is not signed by the Amazon root CA. ## Fetch configuration from Amazon Parameter Store Amazon IoT Device Tester (IDT) includes an optional feature to fetch configuration values from the [Amazon Systems Manager Parameter Store](https://docs.amazonaws.cn/systems-manager/latest/userguide/systems-manager-parameter-store.html). Amazon Parameter Store allows for secure and encrypted storage of configurations. When configured, IDT can fetch parameters from Amazon Parameter Store in place of storing parameters in plaintext inside the `userdata.json` file. This is useful for any sensitive data that should be stored encrypted, such as: passwords, pins, and other secrets. 1. To use this feature, you must update the permissions used in creating your [IDT user](https://docs.amazonaws.cn/greengrass/v2/developerguide/dev-tst-prereqs.html) to allow the GetParameter action on the parameters that IDT is configured to use. The below is an example of a permission statement that can be added to the IDT user. For more information, see [Amazon Systems Manager userguide](https://docs.amazonaws.cn/systems-manager/latest/userguide/sysman-paramstore-access.html). ``` { "Sid":"parameterStoreResources", "Effect": "Allow", "Action": [ "ssm:GetParameter" ], "Resource": "arn:aws:ssm:*:*:parameter/IDT*" } ``` The above permission is configured to allow fetching all parameters with a name beginning with `IDT`, by using the wildcard character `*`. You should customize this to your needs so IDT has access to fetch any configured parameters based on the naming of the parameters you are using. 1. You need to store your configuration values inside Amazon Paramater Store. This can be done from the Amazon console or from the Amazon CLI. Amazon Parameter Store allows you to choose encrypted or unencrypted storage. For storage of sensitive values like secrets, passwords, and pins, you should use the encrypted option which is a parameter type of SecureString. To upload a parameter using the Amazon CLI, you can use the following command: ``` aws ssm put-parameter --name IDT-example-name --value IDT-example-value --type SecureString ``` You can verify that a parameter is stored using the following command. (Optional) Use the `--with-decryption` flag to fetch a decrypted SecureString parameter. ``` aws ssm get-parameter --name IDT-example-name ``` Using the Amazon CLI will upload the parameter in the Amazon region of the current CLI user and IDT will fetch parameters from the region configured in `config.json`. To check your region from the Amazon CLI, use the following: ``` aws configure get region ``` 1. Once you have a configuration value in the Amazon Cloud, you can update any value inside the IDT configuration to fetch from the Amazon Cloud. To do so, you use a placeholder in your IDT configuration of the form `{{AWS.Parameter.parameter_name}}` to fetch the parameter by that name from the Amazon Parameter Store. For example, suppose you want to use the `IDT-example-name` parameter from Step 2 as the HSM keyLabel in your HSM configuration. To do this, you can update your `userdata.json` as follows: ``` "hsm": { "keyLabel": "{{AWS.Parameter.IDT-example-name}}", [...] } ``` IDT will fetch the value of this parameter at runtime that was set to `IDT-example-value` in Step 2. This configuration is similar to setting `"keyLabel": "IDT-example-value"` but, instead, that value is store as encrypted in the Amazon Cloud.