# Components


AWS IoT Greengrass components are software modules that you deploy to Greengrass core devices. Components can represent applications, runtime installers, libraries, or any code that you would run on a device. You can define components that depend on other components. For example, you might define a component that installs Python, and then define that component as a dependency of your components that run Python applications. When you deploy your components to your fleets of devices, Greengrass deploys only the software modules that your devices require.

**Topics**
+ [

# AWS-provided components
](public-components.md)
+ [

# Publisher-supported components
](publisher-supported-components.md)
+ [

# Community components
](greengrass-software-catalog.md)
+ [

# AWS IoT Greengrass development tools
](greengrass-development-tools.md)
+ [

# Develop AWS IoT Greengrass components
](develop-greengrass-components.md)
+ [

# Deploy AWS IoT Greengrass components to devices
](manage-deployments.md)

# AWS-provided components


AWS IoT Greengrass provides and maintains prebuilt components that you can deploy to your devices. These components include features (such as stream manager), AWS IoT Greengrass V1 connectors (such as CloudWatch metrics), and local development tools (such as the AWS IoT Greengrass CLI). You can [deploy these components](manage-deployments.md) to your devices for their standalone functionality, or you can use them as dependencies in your [custom Greengrass components](develop-greengrass-components.md).

**Note**  <a name="component-nucleus-dependency-update-note"></a>
Several AWS-provided components depend on specific minor versions of the Greengrass nucleus. Because of this dependency, you need to update these components when you update the Greengrass nucleus to a new minor version. For information about the specific versions of the nucleus that each component depends on, see the corresponding component topic. For more information about updating the nucleus, see [Update the AWS IoT Greengrass Core software (OTA)](update-greengrass-core-v2.md).

<a name="component-table-type-description"></a>When a component has a component type of both generic and Lambda, the current version of the component is the generic type and a previous version of the component is the Lambda type.


| Component | Description | [Component type](develop-greengrass-components.md#component-types) | Supported OS | [Open source](open-source.md) | Nucleus lite compatible | 
| --- | --- | --- | --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | The nucleus of the AWS IoT Greengrass Core software. Use this component to configure and update the software on your core devices. | Nucleus | Linux, Windows | [Yes](https://github.com/aws-greengrass/aws-greengrass-nucleus) | No | 
| [Greengrass nucleus lite](greengrass-nucleus-lite-component.md) | A lightweight nucleus for resource-constrained devices optimized for low-cost, edge devices and high-volume applications | NucleusLite | Linux | [Yes](https://github.com/aws-greengrass/aws-greengrass-lite) | No | 
| <a name="client-device-auth-component-table-row"></a>[Client device auth](client-device-auth-component.md) | Enables local IoT devices, called client devices, to connect to the core device. | Plugin | Linux, Windows | [Yes](https://github.com/aws-greengrass/aws-greengrass-client-device-auth) | No | 
| [CloudWatch metrics](cloudwatch-metrics-component.md) | Publishes custom metrics to Amazon CloudWatch. | Generic, Lambda | Linux, Windows | [Yes](https://github.com/aws-greengrass/aws-greengrass-cloudwatch-metrics) | Yes | 
| [AWS IoT Device Defender](device-defender-component.md) | Notifies administrators of changes in the state of the Greengrass core device to identify unusual behavior. | Generic, Lambda | Linux, Windows | [Yes](https://github.com/aws-greengrass/aws-greengrass-device-defender) | No | 
| [Disk spooler](disk-spooler-component.md) | Enables a persistent storage option for messages spooled from Greengrass core devices to AWS IoT Core. This component will store these outbound messages on disk. | Plugin | Linux, Windows | [Yes](https://github.com/aws-greengrass/aws-greengrass-disk-spooler) | No | 
| [Docker application manager](docker-application-manager-component.md) | Enables AWS IoT Greengrass to download Docker images from Docker Hub and Amazon Elastic Container Registry (Amazon ECR). | Generic | Linux, Windows | No | No | 
| [Edge connector for Kinesis Video Streams](kvs-edge-connector-component.md) | Reads video feeds from local cameras, publishes the streams to Kinesis Video Streams, and displays the streams in Grafana dashboards with AWS IoT TwinMaker. | Generic | Linux | No | No | 
| [Greengrass CLI](greengrass-cli-component.md) | Provides a command-line interface that you can use to create local deployments and interact with the Greengrass core device and its components. | Plugin | Linux, Windows | [Yes](https://github.com/aws-greengrass/aws-greengrass-cli) | [No](https://github.com/aws-greengrass/aws-greengrass-lite/blob/main/docs/ggl-cli.md) | 
| <a name="ip-detector-component-table-row"></a>[IP detector](ip-detector-component.md) | Reports MQTT broker connectivity information to AWS IoT Greengrass, so client devices can discover how to connect. | Plugin | Linux, Windows | [Yes](https://github.com/aws-greengrass/aws-greengrass-ip-detector) | No | 
| [Firehose](kinesis-firehose-component.md) | Publishes data through Amazon Data Firehose delivery streams to destinations in the AWS Cloud. | Lambda | Linux | No | No | 
| [Lambda launcher](lambda-launcher-component.md) | Handles processes and environment configuration for Lambda functions. | Generic | Linux | No | No | 
| [Lambda manager](lambda-manager-component.md) | Handles interprocess communication and scaling for Lambda functions. | Plugin | Linux | No | No | 
| [Lambda runtimes](lambda-runtimes-component.md) | Provides artifacts for each Lambda runtime. | Generic | Linux | No | No | 
| [Legacy subscription router](legacy-subscription-router-component.md) | Manages subscriptions for Lambda functions that run on AWS IoT Greengrass V1. | Generic | Linux | No | No | 
| [Local debug console](local-debug-console-component.md) | Provides a local console that you can use to debug and manage the Greengrass core device and its components. | Plugin | Linux, Windows | [Yes](https://github.com/aws-greengrass/aws-greengrass-localdebugconsole) | No | 
| [Log manager](log-manager-component.md) | Collects and uploads logs on the Greengrass core device. | Plugin | Linux, Windows | [Yes](https://github.com/aws-greengrass/aws-greengrass-log-manager) | No | 
| [Machine learning components](machine-learning-components.md) | Provides machine learning models and sample inference code that you can use to perform machine learning inference on Greengrass core devices. | See [Machine learning components](machine-learning-components.md). | No | 
| [Modbus-RTU protocol adapter](modbus-rtu-protocol-adapter-component.md) | Polls information from local Modbus RTU devices. | Lambda | Linux | No | No | 
| [Nucleus telemetry emitter](nucleus-emitter-component.md) | Publishes system health telemetry data gathered from the nucleus to a local topic or to an AWS IoT Core MQTT topic. | Plugin | Linux, Windows | [Yes](https://github.com/aws-greengrass/aws-greengrass-telemetry-nucleus-emitter) | No | 
| <a name="mqtt-bridge-component-table-row"></a>[MQTT bridge](mqtt-bridge-component.md) | Relays MQTT messages between client devices, local AWS IoT Greengrass publish/subscribe, and AWS IoT Core. | Plugin | Linux, Windows | [Yes](https://github.com/aws-greengrass/aws-greengrass-mqtt-bridge) | No | 
| <a name="mqtt-broker-moquette-component-table-row"></a>[MQTT 3.1.1 broker (Moquette)](mqtt-broker-moquette-component.md) | Runs an MQTT 3.1.1 broker that handles messages between client devices and the core device. | Plugin | Linux, Windows | [Yes](https://github.com/aws-greengrass/aws-greengrass-moquette-mqtt) | No | 
| <a name="mqtt-broker-emqx-component-table-row"></a>[MQTT 5 broker (EMQX)](mqtt-broker-emqx-component.md) | Runs an MQTT 5 broker that handles messages between client devices and the core device. | Generic | Linux, Windows | No | No | 
| [PKCS\$111 provider](pkcs11-provider-component.md) | Enables Greengrass components to to access a private key and certificate that you securely store in a hardware security module (HSM). | Plugin | Linux | [Yes](https://github.com/aws-greengrass/aws-greengrass-pkcs11-provider) | No | 
| [Secret manager](secret-manager-component.md) | Deploys secrets from AWS Secrets Manager secrets so that you can securely use credentials, such as passwords, in custom components on the Greengrass core device. | Plugin | Linux, Windows | [Yes](https://github.com/aws-greengrass/aws-greengrass-secret-manager) | No | 
| [Secure tunneling](secure-tunneling-component.md) | Enables AWS IoT secure tunneling connections that you can use to establish bidrectional communications with Greengrass core devices that are behind restricted firewalls. | Generic | Linux | No | Yes | 
| <a name="shadow-manager-component-table-row"></a>[Shadow manager](shadow-manager-component.md) | Enables interaction with shadows on the core device. It manages shadow document storage and also the synchronization of local shadow states with the AWS IoT Device Shadow service. | Plugin | Linux, Windows | [Yes](https://github.com/aws-greengrass/aws-greengrass-shadow-manager) | No | 
| [Amazon SNS](sns-component.md) | Publishes messages to Amazon SNS topics. | Lambda | Linux | No | No | 
| [Stream manager](stream-manager-component.md) | Streams high-volume data from local sources to the AWS Cloud. | Generic | Linux, Windows | No | Yes | 
| [System log forwarder](system-log-forwarder-component.md) | Upload systemd-journald logs to the AWS Cloud. | Generic | Linux | [Yes](https://github.com/aws-greengrass/aws-greengrass-system-log-forwarder) | Yes | 
| [Systems Manager Agent](systems-manager-agent-component.md) | Manage the core device with AWS Systems Manager, which enables you to patch devices, run commands, and more. | Generic | Linux | [Yes](https://github.com/aws/amazon-ssm-agent/blob/mainline/packaging/greengrass/component.json) | No | 
| [Token exchange service](token-exchange-service-component.md) | Provides AWS credentials that you can use to interact with AWS services. | Generic | Linux, Windows | No | No | 
| [IoT SiteWise OPC UA collector](iotsitewise-opcua-collector-component.md) | Collects data from OPC-UA servers. | Generic | Linux, Windows | No | No | 
| [IoT SiteWise OPC UA data source simulator](iotsitewise-opcua-data-source-simulator-component.md) | Runs a local OPC-UA server that generates sample data. | Generic | Linux, Windows | No | No | 
| [IoT SiteWise publisher](iotsitewise-publisher-component.md) | Publishes data to the AWS Cloud. | Generic | Linux, Windows | No | No | 
| [IoT SiteWise processor](iotsitewise-processor-component.md) | Processes data on the Greengrass core devices. | Generic | Linux, Windows | No | No | 

# Greengrass nucleus


The Greengrass nucleus component (`aws.greengrass.Nucleus`) is a mandatory component and the minimum requirement to run the AWS IoT Greengrass Core software on a device. You can configure this component to customize and update your AWS IoT Greengrass Core software remotely. Deploy this component to configure settings such as proxy, device role, and AWS IoT thing configuration on your core devices.

**Note**  
As of Greengrass version 2.14.0, a memory footprint optimized version of the nucleus device runtime is available for constrained edge devices. See [Greengrass nucleus lite](https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-lite-component.html) for more information on its configuration and use.

**Important**  
When the version of the nucleus component changes, or when you change certain configuration parameters, the AWS IoT Greengrass Core software—which includes the nucleus and all other components on your device—restarts to apply the changes.   
<a name="component-patch-update"></a>When you deploy a component, AWS IoT Greengrass installs the latest supported versions of all of that component's dependencies. Because of this, new patch versions of AWS-provided public components might be automatically deployed to your core devices if you add new devices to a thing group, or you update the deployment that targets those devices. Some automatic updates, such as a nucleus update, can cause your devices to restart unexpectedly.   
<a name="component-version-pinning"></a>To prevent unintended updates for a component that is running on your device, we recommend that you directly include your preferred version of that component when you [create a deployment](create-deployments.md). For more information about update behavior for AWS IoT Greengrass Core software, see [Update the AWS IoT Greengrass Core software (OTA)](update-greengrass-core-v2.md).

**Topics**
+ [

## Versions
](#greengrass-nucleus-component-versions)
+ [

## Device requirements
](#greengrass-v2-requirements)
+ [

## Supported platforms
](#greengrass-v2-supported-platforms)
+ [

## Operating system
](#greengrass-nucleus-component-os-support)
+ [

## Requirements
](#greengrass-nucleus-component-requirements)
+ [

## Dependencies
](#greengrass-nucleus-component-dependencies)
+ [

## Download and installation
](#greengrass-nucleus-component-install)
+ [

## Configuration
](#greengrass-nucleus-component-configuration)
+ [

## Local log file
](#greengrass-nucleus-component-log-file)
+ [

## Changelog
](#greengrass-nucleus-component-changelog)

## Versions


This component has the following versions:
+ 2.16.x
+ 2.15.x
+ 2.14.x
+ 2.13.x
+ 2.12.x
+ 2.11.x
+ 2.10.x
+ 2.9.x
+ 2.8.x
+ 2.7.x
+ 2.6.x
+ 2.5.x
+ 2.4.x
+ 2.3.x
+ 2.2.x
+ 2.1.x
+ 2.0.x

## Device requirements


**Note**  
You can use AWS IoT Device Tester for AWS IoT Greengrass to verify that your device can run the AWS IoT Greengrass Core software and communicate with the AWS Cloud. For more information, see [Using AWS IoT Device Tester for AWS IoT Greengrass V2](device-tester-for-greengrass-ug.md).

------
#### [ Linux ]
+ <a name="requirement-supported-region"></a>The use of an [AWS Region](https://en.wikipedia.org/wiki/Amazon_Web_Services#Availability_and_topology) that supports AWS IoT Greengrass V2. For the list of supported Regions, see [AWS IoT Greengrass V2 endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/greengrassv2.html) in the *AWS General Reference*.
+ Minimum 256 MB disk space available for the AWS IoT Greengrass Core software. This requirement doesn't include components deployed to the core device.
+ Minimum 96 MB RAM allocated to the AWS IoT Greengrass Core software. This requirement doesn't include components that run on the core device. For more information, see [Control memory allocation with JVM options](configure-greengrass-core-v2.md#jvm-tuning).
+ Java Runtime Environment (JRE) version 8 or greater. Java must be available on the [PATH](https://en.wikipedia.org/wiki/PATH_(variable)) environment variable on the device. To use Java to develop custom components, you must install a Java Development Kit (JDK). 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.
+ [GNU C Library](https://www.gnu.org/software/libc/) (glibc) version 2.25 or greater.
+ You must run the AWS IoT Greengrass Core software as a root user. Use `sudo`, for example.
+ The root user that runs the AWS IoT Greengrass Core software, such as `root`, must have permission to run `sudo` with any user and any group. The `/etc/sudoers` file must give this user permission to run `sudo` as other groups. The permission for the user in `/etc/sudoers` should look like the following example.

  ```
  root    ALL=(ALL:ALL) ALL
  ```
+ The core device must be able to perform outbound requests to a set of endpoints and ports. For more information, see [Allow device traffic through a proxy or firewall](allow-device-traffic.md).
+ The `/tmp` directory must be mounted with `exec` permissions.
+ All of the following shell commands:
  + `ps -ax -o pid,ppid`
  + `sudo`
  + `sh`
  + `kill`
  + `cp`
  + `chmod`
  + `rm`
  + `ln`
  + `echo`
  + `exit`
  + `id`
  + `uname`
  + `grep`
+ Your device may also require the following optional shell commands:
  + (Optional) `systemctl`. This command is used to set up the AWS IoT Greengrass Core software as a system service.
  + (Optional) `useradd`, `groupadd`, and `usermod`. These command are used to set up the `ggc_user` system user and `ggc_group` system group.
  + (Optional) `mkfifo`. This command is used to run Lambda functions as components.
+ To configure system resource limits for component processes, your device must run Linux kernel version 2.6.24 or later.
+ To run Lambda functions, your device must meet additional requirements. For more information, see [Lambda function requirements](setting-up.md#greengrass-v2-lambda-requirements).

------
#### [ Windows ]
+ <a name="requirement-supported-region"></a>The use of an [AWS Region](https://en.wikipedia.org/wiki/Amazon_Web_Services#Availability_and_topology) that supports AWS IoT Greengrass V2. For the list of supported Regions, see [AWS IoT Greengrass V2 endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/greengrassv2.html) in the *AWS General Reference*.
+ Minimum 256 MB disk space available for the AWS IoT Greengrass Core software. This requirement doesn't include components deployed to the core device.
+ Minimum 160 MB RAM allocated to the AWS IoT Greengrass Core software. This requirement doesn't include components that run on the core device. For more information, see [Control memory allocation with JVM options](configure-greengrass-core-v2.md#jvm-tuning).
+ Java Runtime Environment (JRE) version 8 or greater. Java must be available on the [PATH](https://en.wikipedia.org/wiki/PATH_(variable)) system variable on the device. To use Java to develop custom components, you must install a Java Development Kit (JDK). 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.. 
**Note**  
To use version 2.5.0 of the [Greengrass nucleus](#greengrass-nucleus-component), you must use a 64-bit version of the Java Runtime Environment (JRE). Greengrass nucleus version 2.5.1 supports 32-bit and 64-bit JREs.
+ The user who installs the AWS IoT Greengrass Core software must be an administrator.
+ You must install the AWS IoT Greengrass Core software as a system service. Specify `--setup-system-service true` when you install the software.
+ Each user that runs component processes must exist in the LocalSystem account, and the user's name and password must be in the Credential Manager instance for the LocalSystem account. You can set up this user when you follow instructions to [install the AWS IoT Greengrass Core software](install-greengrass-core-v2.md).
+ The core device must be able to perform outbound requests to a set of endpoints and ports. For more information, see [Allow device traffic through a proxy or firewall](allow-device-traffic.md).

------

## Supported platforms


AWS IoT Greengrass officially supports devices running the following platforms. Devices with platforms not included in this list might work, but AWS IoT Greengrass tests on only these specified platforms.

------
#### [ Linux ]

Architectures:
+ Armv7l
+ Armv8 (AArch64)
+ x86\$164

------
#### [ Windows ]

Architectures:
+ x86\$164

Versions:
+ Windows 10
+ Windows 11
+ Windows Server 2019
+ Windows Server 2022

**Note**  
Some AWS IoT Greengrass features aren't currently supported on Windows devices. For more information, see [Greengrass feature compatibility](operating-system-feature-support-matrix.md) and [Feature considerations](#greengrass-v2-windows-feature-considerations).

------

### Feature considerations


Some AWS IoT Greengrass features aren't currently supported on Windows devices. Review the feature differences to confirm if a Windows device satisfies your requirements. For more information, see [Greengrass feature compatibility](operating-system-feature-support-matrix.md).

To build a custom Linux-based operating system, you can use the BitBake recipe for AWS IoT Greengrass in the [`meta-aws` project](https://github.com/aws/meta-aws/tree/master/recipes-iot). The `meta-aws` project provides recipes that you can use to build AWS edge software capabilities in [embedded Linux](https://elinux.org/) systems that are built with [OpenEmbedded](https://www.openembedded.org/wiki/Main_Page) and Yocto Project build frameworks. The [Yocto Project](https://www.yoctoproject.org/) is an open source collaboration project that helps you build custom Linux-based systems for embedded applications regardless of hardware architecture. The BitBake recipe for AWS IoT Greengrass installs, configures, and automatically runs the AWS IoT Greengrass Core software on your device.

Linux platforms can also run AWS IoT Greengrass in a Docker container. For more information, see [Run AWS IoT Greengrass Core software in a Docker container](run-greengrass-docker.md). 

## Operating system


This component can be installed on core devices that run the following operating systems:
+ Linux
+ Windows

For more information, see [Supported platforms](#greengrass-v2-supported-platforms).

## Requirements


Devices must meet certain requirements to install and run the Greengrass nucleus and the AWS IoT Greengrass Core software. For more information, see [Device requirements](#greengrass-v2-requirements).

The Greengrass nucleus component is supported to run in a VPC. To deploy this component in a VPC, the following is required.
+ The Greengrass nucleus component must have connectivity to AWS IoT data, AWS IoT Credentials, and Amazon S3.

## Dependencies


The Greengrass nucleus does not include any component dependencies. However, several AWS-provided components include the nucleus as a dependency. For more information, see [AWS-provided components](public-components.md).

For more information about component dependencies, see the [component recipe reference](component-recipe-reference.md#recipe-reference-component-dependencies).

## Download and installation


You can download an installer that sets up the Greengrass nucleus component on your device. This installer sets up your device as a Greengrass core device. There are two types of installations that you can perform: a quick installation that creates required AWS resources for you, or a manual installation where you create the AWS resources yourself. For more information, see [Install the AWS IoT Greengrass Core software](install-greengrass-core-v2.md).

You can also follow a tutorial to install the Greengrass nucleus and explore Greengrass component development. For more information, see [Tutorial: Getting started with AWS IoT Greengrass V2](getting-started.md).

## Configuration


This component provides the following configuration parameters that you can customize when you deploy the component. Some parameters require that the AWS IoT Greengrass Core software restarts to take effect. For more information about why and how to configure this component, see [Configure the AWS IoT Greengrass Core software](configure-greengrass-core-v2.md).

`iotRoleAlias`  
<a name="nucleus-component-configuration-iot-role-alias"></a>The AWS IoT role alias that points to a token exchange IAM role. The AWS IoT credentials provider assumes this role to allow the Greengrass core device to interact with AWS services. For more information, see [Authorize core devices to interact with AWS services](device-service-role.md).  
When you run the AWS IoT Greengrass Core software with the `--provision true` option, the software provisions a role alias and sets its value in the nucleus component.

  `interpolateComponentConfiguration`   
(Optional) You can enable the Greengrass nucleus to interpolate [component recipe variables](component-recipe-reference.md#recipe-variables) in component configurations and [merge configuration updates](update-component-configurations.md#merge-configuration-update-recipe-variables). We recommend that you set this option to `true` so that the core device can run Greengrass components that use recipe variables in their configurations.  
This feature is available for v2.6.0 and later of this component.  
Default: `false`

`networkProxy`  
(Optional) The network proxy to use for all connections. For more information, see [Connect on port 443 or through a network proxy](configure-greengrass-core-v2.md#configure-alpn-network-proxy).  
<a name="nucleus-component-parameter-restart-para"></a>When you deploy a change to this configuration parameter, the AWS IoT Greengrass Core software restarts for the change to take effect.
This object contains the following information:    
`noProxyAddresses`  
(Optional) A comma-separated list of IP addresses or hostnames that are exempt from the proxy.  
`proxy`  
The proxy to which to connect. This object contains the following information:    
`url`  
The URL of the proxy server in the format `scheme://userinfo@host:port`.  <a name="nucleus-component-configuration-proxy-url-segments"></a>
+ `scheme` – The scheme, which must be `http` or `https`.
**Important**  
<a name="https-proxy-greengrass-nucleus-requirement"></a>Greengrass core devices must run [Greengrass nucleus ](#greengrass-nucleus-component) v2.5.0 or later to use HTTPS proxies.  
If you configure an HTTPS proxy, you must add the proxy server CA certificate to the core device's Amazon root CA certificate. For more information, see [Enable the core device to trust an HTTPS proxy](configure-greengrass-core-v2.md#https-proxy-certificate-trust).
+ `userinfo` – (Optional) The user name and password information. If you specify this information in the `url`, the Greengrass core device ignores the `username` and `password` fields.
+ `host` – The host name or IP address of the proxy server.
+ `port` – (Optional) The port number. If you don't specify the port, then the Greengrass core device uses the following default values:
  + `http` – 80
  + `https` – 443  
`username`  
(Optional) The user name that authenticates the proxy server.  
`password`  
(Optional) The password that authenticates the proxy server.

`mqtt`  
(Optional) The MQTT configuration for the Greengrass core device. For more information, see [Connect on port 443 or through a network proxy](configure-greengrass-core-v2.md#configure-alpn-network-proxy).  
<a name="nucleus-component-parameter-restart-para"></a>When you deploy a change to this configuration parameter, the AWS IoT Greengrass Core software restarts for the change to take effect.
This object contains the following information:    
`port`  
(Optional) The port to use for MQTT connections.  
Default: `8883`  
`keepAliveTimeoutMs`  
(Optional) The amount of time in milliseconds between each `PING` message that the client sends to keep the MQTT connection alive. This value must be greater than `pingTimeoutMs`.  
Default: `60000` (60 seconds)  
`pingTimeoutMs`  
(Optional) The amount of time in milliseconds that the client waits to receive a `PINGACK` message from the server. If the wait exceeds the timeout, the core device closes and reopens the MQTT connection. This value must be less than `keepAliveTimeoutMs`.  
Default: `30000` (30 seconds)  
`operationTimeoutMs`  
(Optional) The amount of time in milliseconds that the client waits for MQTT operations (such as `CONNECT` or `PUBLISH`) to complete. This option doesn't apply to MQTT `PING` or keep alive messages.  
Default: `30000` (30 seconds)  
`maxInFlightPublishes`  
(Optional) The maximum number of unacknowledged MQTT QoS 1 messages that can be in flight at the same time.  
This feature is available for v2.1.0 and later of this component.  
Default: `5`  
Valid range: Maximum value of 100  
`maxMessageSizeInBytes`  
(Optional) The maximum size of an MQTT message. If a message exceeds this size, the Greengrass nucleus rejects the message with an error.  
This feature is available for v2.1.0 and later of this component.  
Default: `131072` (128 KB)  
Valid range: Maximum value of `2621440` (2.5 MB)  
`maxPublishRetry`  
(Optional) The maximum number of times to retry a message that fails to publish. You can specify `-1` to retry unlimited times.  
This feature is available for v2.1.0 and later of this component.  
Default: `100`  
`spooler`  
(Optional) The MQTT spooler configuration for the Greengrass core device. This object contains the following information:    
`storageType`  
The storage type for storing messages. If `storageType` is set to `Disk`, the `pluginName` can be configured. You can specify either `Memory` or `Disk`.  
This feature is available for v2.11.0 and later of the [Greengrass nucleus component](#greengrass-nucleus-component).  
If the MQTT spooler `storageType` is set to `Disk` and you want to downgrade Greengrass nucleus from version 2.11.x to an earlier version, you must change the configuration back to `Memory`. The only configuration for `storageType` that is supported in Greengrass nucleus versions 2.10.x and earlier is `Memory`. Not following this guidance can result in the spooler breaking. This would cause your Greengrass core device to not be able to send MQTT messages to the AWS Cloud.
Default: `Memory`  
`pluginName`  
(Optional) The plugin component name. This component will only be used if `storageType` is set to `Disk`. This option defaults to `aws.greengrass.DiskSpooler` and will use the Greengrass-provided [Disk spooler](disk-spooler-component.md).  
This feature is available for v2.11.0 and later of the [Greengrass nucleus component](#greengrass-nucleus-component).  
Default: `"aws.greengrass.DiskSpooler"`  
`maxSizeInBytes`  
(Optional) The maximum size of the cache where the core device stores unprocessed MQTT messages in memory. If the cache is full, new messages are rejected.  
Default: `2621440` (2.5 MB)  
`keepQos0WhenOffline`  
(Optional) You can spool MQTT QoS 0 messages that the core device receives while its offline. If you set this option to `true`, the core device spools QoS 0 messages that it can't send while it's offline. If you set this option to `false`, the core device discards these messages. The core device always spools QoS 1 messages unless the spool is full.  
Default: `false`  
`version`  
(Optional) The version of MQTT. You can specify either `mqtt3` or `mqtt5`.  
This feature is available for v2.10.0 and later of the [Greengrass nucleus component](#greengrass-nucleus-component).  
Default: `mqtt5`  
`receiveMaximum`  
(Optional) The maximum number of unacknowledged QoS1 packets the broker can send.  
This feature is available for v2.10.0 and later of the [Greengrass nucleus component](#greengrass-nucleus-component).  
Default: `100`  
`sessionExpirySeconds`  
(Optional) The amount of time in seconds you can request for a session to last from IoT Core. The default is the maximum time supported by AWS IoT Core.  
This feature is available for v2.10.0 and later of the [Greengrass nucleus component](#greengrass-nucleus-component).  
Default: `604800 (7 days)`  
`minimumReconnectDelaySeconds`  
(Optional) An option for reconnection behavior. The minimum amount of time in seconds for MQTT to reconnect.  
This feature is available for v2.10.0 and later of the [Greengrass nucleus component](#greengrass-nucleus-component).  
Default: `1`  
`maximumReconnectDelaySeconds`  
(Optional) An option for reconnection behavior. The maximum amount of time in seconds for MQTT to reconnect.  
This feature is available for v2.10.0 and later of the [Greengrass nucleus component](#greengrass-nucleus-component).  
Default: `120`  
`minimumConnectedTimeBeforeRetryResetSeconds`  
(Optional) An option for reconnection behavior. The amount of time in seconds a connection must be active before the retry delay is reset back to the minimum.  
This feature is available for v2.10.0 and later of the [Greengrass nucleus component](#greengrass-nucleus-component).  
Default: `30`

  `jvmOptions`  
(Optional) The JVM options to use to run the AWS IoT Greengrass Core software. For information about recommended JVM options for running AWS IoT Greengrass Core software, see [Control memory allocation with JVM options](configure-greengrass-core-v2.md#jvm-tuning).  
<a name="nucleus-component-parameter-restart-para"></a>When you deploy a change to this configuration parameter, the AWS IoT Greengrass Core software restarts for the change to take effect.

`iotDataEndpoint`  
<a name="nucleus-component-configuration-iot-data-endpoint"></a>The AWS IoT data endpoint for your AWS account.  
<a name="nucleus-component-set-iot-endpoints"></a>When you run the AWS IoT Greengrass Core software with the `--provision true` option, the software gets your data and credentials endpoints from AWS IoT and sets them in the nucleus component.

`iotCredEndpoint`  
<a name="nucleus-component-configuration-iot-cred-endpoint"></a>The AWS IoT credentials endpoint for your AWS account.  
<a name="nucleus-component-set-iot-endpoints"></a>When you run the AWS IoT Greengrass Core software with the `--provision true` option, the software gets your data and credentials endpoints from AWS IoT and sets them in the nucleus component.

`greengrassDataPlaneEndpoint`  
This feature is available in v2.7.0 and later of this component.  
For more information, see [Use a device certificate signed by a private CA](configure-greengrass-core-v2.md#configure-nucleus-private-ca).

`greengrassDataPlanePort`  
This feature is available in v2.0.4 and later of this component.  
(Optional) The port to use for data plane connections. For more information, see [Connect on port 443 or through a network proxy](configure-greengrass-core-v2.md#configure-alpn-network-proxy).  
You must specify a port where the device can make outbound connections. If you specify a port that is blocked, the device won't be able to connect to AWS IoT Greengrass to receive deployments.
Choose from the following options:  
+ `443`
+ `8443`
Default: `8443`

`awsRegion`  
The AWS Region to use.

`runWithDefault`  
The system user to use to run components.  
<a name="nucleus-component-parameter-restart-para"></a>When you deploy a change to this configuration parameter, the AWS IoT Greengrass Core software restarts for the change to take effect.
This object contains the following information:    
`posixUser`  
The name or ID of the system user and, optionally, system group that the core device uses to run generic and Lambda components. Specify the user and group separated by a colon (`:`) in the following format: `user:group`. The group is optional. If you don't specify a group, the AWS IoT Greengrass Core software uses the primary group for the user. For example, you can specify `ggc_user` or `ggc_user:ggc_group`. For more information, see [Configure the user that runs components](configure-greengrass-core-v2.md#configure-component-user).  
When you run the AWS IoT Greengrass Core software installer with the `--component-default-user ggc_user:ggc_group` option, the software sets this parameter in the nucleus component.  
`windowsUser`  
This feature is available in v2.5.0 and later of this component.  
The name of the Windows user to use to run this component on Windows core devices. The user must exist on each Windows core device, and its name and password must be stored in the LocalSystem account's Credentials Manager instance. For more information, see [Configure the user that runs components](configure-greengrass-core-v2.md#configure-component-user).  
When you run the AWS IoT Greengrass Core software installer with the `--component-default-user ggc_user` option, the software sets this parameter in the nucleus component.  
`systemResourceLimits`  
This feature is available in v2.4.0 and later of this component. AWS IoT Greengrass doesn't currently support this feature on Windows core devices.   
The system resource limits to apply to generic and non-containerized Lambda component processes by default. You can override system resource limits for individual components when you create a deployment. For more information, see [Configure system resource limits for components](configure-greengrass-core-v2.md#configure-component-system-resource-limits).  
This object contains the following information:    
`cpus`  
 <a name="system-resource-limits-cpu-definition-each"></a>The maximum amount of CPU time that each component's processes can use on the core device. A core device's total CPU time is equivalent to the device's number of CPU cores. For example, on a core device with 4 CPU cores, you can set this value to `2` to limit each component's processes to 50 percent usage of each CPU core. On a device with 1 CPU core, you can set this value to `0.25` to limit each component's processes to 25 percent usage of the CPU. If you set this value to a number greater than the number of CPU cores, the AWS IoT Greengrass Core software doesn't limit the components' CPU usage.   
`memory`  
 <a name="system-resource-limits-memory-definition-each"></a>The maximum amount of RAM (in kilobytes) that each component's processes can use on the core device. 

 `s3EndpointType`   
(Optional) The S3 endpoint type. This parameter will only take effect for the US East (N. Virginia) (`us-east-1`) Region. Setting this parameter from any other Region will be ignored. Choose from the following options:  
+ `REGIONAL` – S3 client and presigned URL uses the regional endpoint.
+ `GLOBAL` – S3 client and presigned URL uses the legacy endpoint.
+ `DUALSTACK` – S3 presigned URL uses the dualstack endpoint.
Default: `GLOBAL`

 `fipsMode`   
(Optional) Causes Greengrass to use FIPS endpoints. For more information on how to enable FIPS endpoints, see [FIPS endpoints](FIPS.html).  
Choose from the following options:  
+ `true` When set to true the endpoints will use FIPS endpoint.
+ `false` When false the endpoints will not use FIPS endpoint.
Default: `false`

`logging`  
(Optional) The logging configuration for the core device. For more information about how to configure and use Greengrass logs, see [Monitor AWS IoT Greengrass logs](monitor-logs.md).  
This object contains the following information:    
  `level`   
(Optional) The minimum level of log messages to output.  
Choose from the following log levels, listed here in level order:  <a name="nucleus-log-levels"></a>
+ `DEBUG`
+ `INFO`
+ `WARN`
+ `ERROR`
Default: `INFO`  
  `format`   
(Optional) The data format of the logs. Choose from the following options:  
+ `TEXT` – Choose this option if you want to view logs in text form.
+ `JSON` – Choose this option if you want to view logs with the [Greengrass CLI logs command](gg-cli-logs.md) or interact with logs programmatically.
Default: `TEXT`  
`outputType`  
(Optional) The output type for logs. Choose from the following options:  
+ `FILE` – The AWS IoT Greengrass Core software outputs logs to files in the directory that you specify in `outputDirectory`.
+ `CONSOLE` – The AWS IoT Greengrass Core software prints logs to `stdout`. Choose this option to view logs as the core device prints them.
Default: `FILE`  
  `fileSizeKB`   
(Optional) The maximum size of each log file (in kilobytes). After a log file exceeds this maximum file size, the AWS IoT Greengrass Core software creates a new log file.  
<a name="nucleus-component-logging-parameter-file-only"></a>This parameter applies only when you specify `FILE` for `outputType`.  
Default: `1024`  
  `totalLogsSizeKB`   
(Optional) The maximum total size of log files (in kilobytes) for each component, including the Greengrass nucleus. The Greengrass nucleus' log files also include logs from [plugin components](develop-greengrass-components.md#component-types). After a component's total size of log files exceeds this maximum size, the AWS IoT Greengrass Core software deletes that component's oldest log files.  
This parameter is equivalent to the [log manager component's](log-manager-component.md) [disk space limit](log-manager-component.md#log-manager-component-configuration) parameter (`diskSpaceLimit`), which you can specify for the Greengrass nucleus (system) and each component. The AWS IoT Greengrass Core software uses the minimum of the two values as the maximum total log size for the Greengrass nucleus and each component.  
<a name="nucleus-component-logging-parameter-file-only"></a>This parameter applies only when you specify `FILE` for `outputType`.  
Default: `10240`  
  `outputDirectory`   
(Optional) The output directory for log files.  
<a name="nucleus-component-logging-parameter-file-only"></a>This parameter applies only when you specify `FILE` for `outputType`.  
Default: `/greengrass/v2/logs`, where `/greengrass/v2` is the AWS IoT Greengrass root folder.

  `fleetstatus`   
This parameter is available in v2.1.0 and later of this component.  
(Optional) The fleet status configuration for the core device.  
This object contains the following information:    
`periodicStatusPublishIntervalSeconds`  
(Optional) The amount of time (in seconds) between which the core device publishes device status to the AWS Cloud.  
Minimum: `86400` (24 hours)  
Default: `86400` (24 hours)

  `telemetry`   
(Optional) The system health telemetry configuration for the core device. For more information about telemetry metrics and how to act on telemetry data, see [Gather system health telemetry data from AWS IoT Greengrass core devices](telemetry.md).  
This object contains the following information:    
`enabled`  
(Optional) You can enable or disable telemetry.  
Default: `true`  
`periodicAggregateMetricsIntervalSeconds`  
(Optional) The interval (in seconds) over which the core device aggregates metrics.  
If you set this value lower than the minimum supported value, the nucleus uses the default value instead.  
Minimum: `3600`  
Default: `3600`  
`periodicPublishMetricsIntervalSeconds`  
(Optional) The amount of time (in seconds) between which the core device publishes telemetry metrics to the AWS Cloud.  
If you set this value lower than the minimum supported value, the nucleus uses the default value instead.  
Minimum: `86400`  
Default: `86400`

`deploymentPollingFrequencySeconds`  
(Optional) The period in seconds at which to poll for deployment notifications.  
Default: `15`

`componentStoreMaxSizeBytes`  
(Optional) The maximum size on disk of the component store, which comprises component recipes and artifacts.  
Default: `10000000000` (10 GB)

  `platformOverride`   
(Optional) A dictionary of attributes that identify the core device's platform. Use this to define custom platform attributes that component recipes can use to identify the correct lifecycle and artifacts for the component. For example, you might define a hardware capability attribute to deploy only the minimal set of artifacts for a component to run. For more information, see the [manifest platform parameter](component-recipe-reference.md#component-platform-definition) in the component recipe.  
You can also use this parameter to override the `os` and `architecture` platform attributes of the core device.

  `httpClient`   
This parameter is available in v2.5.0 and later of this component.  
(Optional) The HTTP client configuration for the core device. These configuration options apply to all HTTP requests made by this component. If a core device runs on a slower network, you can increase these timeout durations to prevent HTTP requests from timing out.  
This object contains the following information:    
`connectionTimeoutMs`  
(Optional) The amount of time (in milliseconds) to wait for a connection to open before the connection request times out.  
Default: `2000` (2 seconds)  
`socketTimeoutMs`  
(Optional) The amount of time (in milliseconds) to wait for data to transfer over an open connection before the connection times out.  
Default: `30000` (30 seconds)

  `deploymentConfigurationTimeSource`   
This parameter is available in v2.15.0 and later of this component.  
(Optional) The timestamp to use when processing a deployment. The default is the `deploymentCreationTime`.  
This object contains the following values:    
`deploymentCreationTime`  
The default value of `deploymentConfigurationTimeSource`. The device uses the deployment creation timestamp to resolve configuration key conflicts during processing. When this behavior is selected, local device configuration held by the nucleus may have a greater timestamp than that of the incoming deployment and rejects incoming configuration changes which are now considered outdated.  
`deploymentProcessingTime`  
The device uses its local timestamp to resolve configuration key conflicts during deployment processing. When processed, the device updates configurations based on the processing timestamp rather than the deployment creation timestamp. This behavior assumes the device clock is properly calibrated.  
Configure this nucleus setting in your initial device image or installation rather than through a deployment when you want new devices to use this behavior on first connection. Use the [https://docs.aws.amazon.com/greengrass/v2/developerguide/configure-installer.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/configure-installer.html) option of the nucleus classic installer for this configuration.  
This initial configuration is essential because devices process multiple deployments in arbitrary order. Without proper initial configuration, a device might process deployments using the default `deploymentCreationTime` behavior before receiving the deployment that sets the nucleus configuration to `deploymentProcessingTime`.

**Example: Configuration merge update**  

```
{
  "iotRoleAlias": "GreengrassCoreTokenExchangeRoleAlias",
  "networkProxy": {
    "noProxyAddresses": "http://192.168.0.1,www.example.com",
    "proxy": {
      "url": "http://my-proxy-server:1100",
      "username": "Mary_Major",
      "password": "pass@word1357"
    }
  },
  "mqtt": {
    "port": 443
  },
  "greengrassDataPlanePort": 443,
  "jvmOptions": "-Xmx64m",
  "runWithDefault": {
    "posixUser": "ggc_user:ggc_group"
  }
}
```

## Local log file


This component uses the following log file.

------
#### [ Linux ]

```
/greengrass/v2/logs/greengrass.log
```

------
#### [ Windows ]

```
C:\greengrass\v2\logs\greengrass.log
```

------

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the path to the AWS IoT Greengrass root folder.

------
#### [ Linux ]

  ```
  sudo tail -f /greengrass/v2/logs/greengrass.log
  ```

------
#### [ Windows (PowerShell) ]

  ```
  Get-Content C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
  ```

------

## Changelog


The following table describes the changes in each version of the component.


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.16.1  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.16.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.15.1  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.15.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.14.3  |  Bug fixes and improvements [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.14.2  |  Bug fixes and improvements [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.14.1  |  Bug fixes and improvements [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.14.0  |  This version is no longer available. The improvements in this version are available in later versions of this component.  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.13.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.12.6  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.12.5  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.12.4  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.12.3  |   This version is no longer available. The improvements in this version are available in later versions of this component.  Bug fixes and improvements [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.12.2  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.12.1  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.12.0  |  <a name="changelog-nucleus-2.12.0"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.11.3  |  <a name="changelog-nucleus-2.11.3"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.11.2  |  <a name="changelog-nucleus-2.11.2"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.11.1  |  <a name="changelog-nucleus-2.11.1"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.11.0  |  <a name="changelog-nucleus-2.11.0"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.10.3  |  <a name="changelog-nucleus-2.10.3"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.10.2  |  <a name="changelog-nucleus-2.10.2"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.10.1  |  <a name="changelog-nucleus-2.10.1"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.10.0  |  <a name="changelog-nucleus-2.10.0"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.9.6  |  <a name="changelog-nucleus-2.9.6"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.9.5  |  <a name="changelog-nucleus-2.9.5"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.9.4  |  <a name="changelog-nucleus-2.9.4"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.9.3  |  <a name="changelog-nucleus-2.9.3"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.9.2  |  <a name="changelog-nucleus-2.9.2"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.9.1  |  <a name="changelog-nucleus-2.9.1"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.9.0  |  <a name="changelog-nucleus-2.9.0"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.8.1  |  <a name="changelog-nucleus-2.8.1"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.8.0  |  <a name="changelog-nucleus-2.8.0"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.7.0  |  <a name="changelog-nucleus-2.7.0"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.6.0  |  <a name="changelog-nucleus-2.6.0"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.5.6  |  <a name="changelog-nucleus-2.5.6"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.5.5  |  <a name="changelog-nucleus-2.5.5"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.5.4  |  <a name="changelog-nucleus-2.5.4"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.5.3  |  <a name="changelog-nucleus-2.5.3"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.5.2  |  <a name="changelog-nucleus-2.5.2"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.5.1  |   This version is no longer available. The improvements in this version are available in later versions of this component.  <a name="changelog-nucleus-2.5.1"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.5.0  |  <a name="changelog-nucleus-2.5.0"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.4.0  |  <a name="changelog-nucleus-2.4.0"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.3.0  |  <a name="changelog-nucleus-2.3.0"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.2.0  |  <a name="changelog-nucleus-2.2.0"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.1.0  |  <a name="changelog-nucleus-2.1.0"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.0.5  |  <a name="changelog-nucleus-2.0.5"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.0.4  |  <a name="changelog-nucleus-2.0.4"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  2.0.3  |  Initial version.  | 

# Greengrass nucleus lite
Greengrass nucleus lite component v2.3.2 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-lite-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-lite-component.html)

Version 2.3.2 of the Greengrass nucleus lite component is available. This version updates the version file for correct nucleus version reporting.Greengrass nucleus lite component v2.3.1 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-lite-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-lite-component.html)

Version 2.3.1 of the Greengrass nucleus lite component is available. This version includes several bug fixes and improvements.Greengrass nucleus lite component v2.3.0 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-lite-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-lite-component.html)

Version 2.3.0 of the Greengrass nucleus lite component is available. This version adds support for TPM 2.0, a wider range of operating systems, and RestartComponent IPC. This version also includes several other bug fixes and improvements.Greengrass nucleus lite component v2.2.2 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-lite-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-lite-component.html)

Version 2.2.2 of the Greengrass nucleus lite component is available. This version includes several bug fixes and improvements.Greengrass nucleus lite component v2.2.1 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-lite-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-lite-component.html)

Version 2.2.1 of the Greengrass nucleus lite component is available. This version fixes an issue where the nucleus fails to obtain TES credentials.Greengrass nucleus lite component v2.2.0 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-lite-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-lite-component.html)

Version 2.2.0 of the Greengrass nucleus lite component is available. This version adds support for container image artifact URIs.Greengrass nucleus lite component v2.1.0 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-lite-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-lite-component.html)

Version 2.1.0 of the Greengrass nucleus lite component is available. This version adds HTTP proxy support. This version also includes several other bug fixes and improvements.Greengrass nucleus lite component v2.0.2 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-lite-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-lite-component.html)

Version 2.0.2 of the Greengrass nucleus lite component is available. This version includes general bug fixes and improvements.Greengrass nucleus lite component v2.0.1 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-lite-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-lite-component.html)

Version 2.0.1 of the Greengrass nucleus lite component is available. This version includes general bug fixes and improvements.Greengrass nucleus lite component v2.0.0 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-lite-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-lite-component.html)

Version 2.0.0 of the Greengrass nucleus lite component is available. This is the initial version.

The Greengrass nucleus lite (`aws.greengrass.NucleusLite`) is a device runtime for constrained edge devices optimized for minimal memory footprint (uses less than 5MB RAM). It has been introduced with AWS IoT Greengrass version 2.14.0 release and is backward compatible with AWS IoT Greengrass generic components, Greengrass V2 API, and SDK.

The Greengrass nucleus lite is offered as an alternative to the common [Greengrass nucleus (`aws.greengrass.Nucleus`)](https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html) and can be used in heterogeneous fleets of Greengrass devices.

**Topics**
+ [

## Versions
](#greengrass-nucleus-lite-component-versions)
+ [

## Operating system
](#greengrass-nucleus-lite-component-os-support)
+ [

## Requirements
](#greengrass-nucleus-lite-component-requirements)
+ [

## Compatibility
](#greengrass-nucleus-lite-component-compatibility)
+ [

## Download and installation
](#greengrass-nucleus-lite-component-install)
+ [

## Configuration
](#greengrass-nucleus-lite-component-configuration)
+ [

## Local log file
](#greengrass-nucleus-lite-component-log-file)
+ [

## Changelog
](#greengrass-nucleus-lite-component-changelog)

## Versions


This component has the following versions:
+ 2.3.x
+ 2.2.x
+ 2.1.x
+ 2.0.x

## Operating system


This component can be installed on core devices that run the following operating systems:
+ Linux (distributions with systemd)

For more information, see [Greengrass nucleus](https://docs.aws.amazon.com/greengrass/v2/developerguide/operating-system-feature-support-matrix.html).

## Requirements


Devices must meet certain requirements to install and run the AWS IoT Greengrass nucleus lite and the AWS IoT Greengrass Core software. For more information, see [Setup guide](https://github.com/aws-greengrass/aws-greengrass-lite/blob/main/docs/SETUP.md#setting-up-greengrass-nucleus-lite).
+ 5MB of RAM space for the nucleus runtime.
+ 5MB of storage (disk/FLASH).

Additional system dependencies are documented in the [Setup Guide](https://github.com/aws-greengrass/aws-greengrass-lite/blob/main/docs/SETUP.md#dependencies).

The Greengrass nucleus component is supported to run in a VPC. To deploy this component in a VPC, the following is required:
+ The Greengrass nucleus must have connectivity to AWS IoT data, AWS IoT Credentials, and Amazon S3.

## Compatibility


The AWS IoT Greengrass nucleus lite is compatible with the AWS IoT Greengrass v2 API (subset of) and supported SDKs. It does not depend on any specific language runtimes/VMs but components added to a deployment can require the presence of specific runtimes (e.g.: Java JVM, Python). For more information about what features are supported with Greengrass nucleus lite, see [Greengrass feature compatibility](operating-system-feature-support-matrix.md).

## Download and installation


You can download an apt package, [build from source](https://github.com/aws-greengrass/aws-greengrass-lite/blob/main/README.md#getting-started), [use a Yocto layer](https://github.com/aws4embeddedlinux/meta-aws), or [download a pre-built Yocto image](https://github.com/aws4embeddedlinux/meta-aws-demos) for compatible device (e.g., RaspberryPi). From the [AWS IoT Core Console](https://console.aws.amazon.com/iot/home) you will be able to download a **connection kit** containing all the credentials and initial configuration for your device. Instructions on how to install are included in each specific distribution method.

You can also follow a tutorial to install the AWS IoT Greengrass nucleus lite and explore Greengrass component development. For more information, see [Tutorial: Getting started with AWS IoT Greengrass V2](getting-started.md).

## Configuration


The nucleus provides the following [configuration](https://github.com/aws-greengrass/aws-greengrass-lite/blob/main/docs/SETUP.md#configuring-greengrass) parameters. Some parameters require that the AWS IoT Greengrass Core software restarts to take effect.

`iotRoleAlias`  
The AWS IoT role alias that points to a token exchange IAM role. The AWS IoT credentials provider assumes this role to allow the Greengrass core device to interact with AWS services. For more information, see [Authorize core devices to interact with AWS services.](https://docs.aws.amazon.com/greengrass/v2/developerguide/device-service-role.html)

`iotDataEndpoint`  
<a name="nucleus-component-configuration-iot-data-endpoint"></a>The AWS IoT data endpoint for your AWS account.

`iotCredEndpoint`  
<a name="nucleus-component-configuration-iot-cred-endpoint"></a>The AWS IoT credentials endpoint for your AWS account.

`greengrassDataPlanePort`  
The port to use for data plane connections. For more information, see [Connect on port 443 or through a network proxy](https://docs.aws.amazon.com/greengrass/v2/developerguide/configure-greengrass-core-v2.html#configure-alpn-network-proxy).  
You must specify a port where the device can make outbound connections. If you specify a port that is blocked, the device won't be able to connect to AWS IoT Greengrass to receive deployments. Choose from the following options:  
+ `443`
+ `8443`
+ Default: `8443`

`awsRegion`  
The AWS Region to use.

`runWithDefault`  
The system user to use to run components.  
<a name="nucleus-component-parameter-restart-para"></a>When you deploy a change to this configuration parameter, the AWS IoT Greengrass Core software restarts for the change to take effect.
This object contains the following information:    
`posixUser`  
The name or ID of the system user and, optionally, system group that the core device uses to run generic components. Specify the user and group separated by a colon (`:`) in the following format: `user:group`. The group is optional. If you don't specify a group, the AWS IoT Greengrass Core software uses the primary group for the user. For example, you can specify `ggc_user` or `ggc_user:ggc_group`. For more information, see [Configure the user that runs components](configure-greengrass-core-v2.md#configure-component-user).

`networkProxy`  
(Optional) The network proxy to use for all connections. For more information, see [Connect on port 443 or through a network proxy](configure-greengrass-core-v2.md#configure-alpn-network-proxy).  
When you deploy a change to this configuration parameter, the change will take effect after the next restart of the AWS IoT Greengrass Core software.
This object contains the following information:    
`noProxyAddresses`  
(Optional) A comma-separated list of IP addresses or hostnames that are exempt from the proxy.  
`proxy`  
The proxy to which to connect. This object contains the following information:    
`url`  
The URL of the proxy server in the format `http://host:port`.  
+ `scheme` – The scheme, which must be `http`.
+ `host` – The host name or IP address of the proxy server.
+ `port` – (Optional) The port number. If you don't specify the port, then the Greengrass core device uses the following default value:
  + `http` – 80

## Local log file


Messages are logged to stdout and log files are handled by systemd.

**To view this component's logs**
+ Use `journalctl` to view logs.

## Changelog



|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.3.2  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-lite-component.html)  | 
|  2.3.1  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-lite-component.html)  | 
|  2.3.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-lite-component.html)  | 
|  2.2.2  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-lite-component.html)  | 
|  2.2.1  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-lite-component.html)  | 
|  2.2.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-lite-component.html)  | 
|  2.1.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-lite-component.html)  | 
|  2.0.2  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-lite-component.html)  | 
|  2.0.1  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-lite-component.html)  | 
|  2.0.0  |  Initial version.  | 

# Client device auth
Client device auth component v2.5.3 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/client-device-auth-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/client-device-auth-component.html)

Client device auth component v2.5.3 is available. This release fixes an issue where client devices are unable to connect to the core device due to out of date client certificates.Client device auth component v2.5.2 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/client-device-auth-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/client-device-auth-component.html)

Client device auth component v2.5.2 is available.Client device auth component v2.5.1 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/client-device-auth-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/client-device-auth-component.html)

Client device auth component v2.5.0 is available. This release adds support for FIPS endpoint.Client device auth component v2.5.0 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/client-device-auth-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/client-device-auth-component.html)

Client device auth component v2.5.0 is available. This release adds policy variable support for thing names. This release also allows policy resources with wildcards.Client device auth component v2.4.5 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/client-device-auth-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/client-device-auth-component.html)

Client device auth component v2.4.5 is available. This release adds support for wildcards at the end of thing names in a selection rule and fixes an issue where certificates are not updated with new connectivity info in certain cases.Client device auth component v2.4.0 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/client-device-auth-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/client-device-auth-component.html)

Client device auth component v2.4.0 is available. This release adds support for client device auth to emit operational metrics that can be displayed on the Greengrass Client Device dashboard.Client device auth component v2.3.2 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/client-device-auth-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/client-device-auth-component.html)

Client device auth component v2.3.2 is available. This release adds support for caching hostname information so that the component correctly generates certificate subjects when restarted while offline.

The client device auth component (`aws.greengrass.clientdevices.Auth`) authenticates client devices and authorizes client device actions.

**Note**  <a name="client-device-component-context"></a>
Client devices are local IoT devices that connect to a Greengrass core device to send MQTT messages and data to process. For more information, see [Interact with local IoT devices](interact-with-local-iot-devices.md).

**Topics**
+ [

## Versions
](#client-device-auth-component-versions)
+ [

## Type
](#client-device-auth-component-type)
+ [

## Operating system
](#client-device-auth-component-os-support)
+ [

## Requirements
](#client-device-auth-component-requirements)
+ [

## Dependencies
](#client-device-auth-component-dependencies)
+ [

## Configuration
](#client-device-auth-component-configuration)
+ [

## Local log file
](#client-device-auth-component-log-file)
+ [

## Changelog
](#client-device-auth-component-changelog)

## Versions


**Note**  
Client device auth version 2.3.0 has been discontinued. We strongly recommend that you upgrade to client device auth version 2.3.1 or later.

This component has the following versions:
+ 2.5.x
+ 2.4.x
+ 2.3.x
+ 2.2.x
+ 2.1.x
+ 2.0.x

## Type


<a name="public-component-type-plugin-para1"></a>This component is a plugin component (`aws.greengrass.plugin`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs this component in the same Java Virtual Machine (JVM) as the nucleus. The nucleus restarts when you change this component's version on the core device.

<a name="public-component-type-plugin-para2"></a>This component uses the same log file as the Greengrass nucleus. For more information, see [Monitor AWS IoT Greengrass logs](monitor-logs.md).

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on core devices that run the following operating systems:
+ Linux
+ Windows

## Requirements


This component has the following requirements:
+ The [Greengrass service role](greengrass-service-role.md) must be associated to your AWS account and allow the `iot:DescribeCertificate` permission.
+ The core device's AWS IoT policy must allow the following permissions:
  + `greengrass:GetConnectivityInfo`, where the resources include the ARN of the core device that runs this component
  + `greengrass:VerifyClientDeviceIoTCertificateAssociation`, where the resources include the Amazon Resource Name (ARN) of each client device that connects to the core device
  + `greengrass:VerifyClientDeviceIdentity`
  + `greengrass:PutCertificateAuthorities`
  + `iot:Publish`, where the resources include the ARN of the following MQTT topic:
    + `$aws/things/coreDeviceThingName*-gci/shadow/get`
  + `iot:Subscribe`, where the resources include the ARNs of the following MQTT topic filters:
    + `$aws/things/coreDeviceThingName*-gci/shadow/update/delta`
    + `$aws/things/coreDeviceThingName*-gci/shadow/get/accepted`
  + `iot:Receive`, where the resources include the ARNs of the following MQTT topics:
    + `$aws/things/coreDeviceThingName*-gci/shadow/update/delta`
    + `$aws/things/coreDeviceThingName*-gci/shadow/get/accepted`

  For more information, see [AWS IoT policies for data plane operations](device-auth.md#iot-policies) and [Minimal AWS IoT policy to support client devices](device-auth.md#client-device-support-minimal-iot-policy).
+ (Optional) To use offline authentication, the AWS Identity and Access Management (IAM) role used by the AWS IoT Greengrass service must contain the following permission:
  + `greengrass:ListClientDevicesAssociatedWithCoreDevice` to enable the core device to list clients for offline authentication.
+ The client device auth component is supported to run in a VPC. To deploy this component in a VPC, the following is required.
  + The client device auth component must have connectivity to AWS IoT data, AWS IoT Credentials, and Amazon S3.

### Endpoints and ports


This component must be able to perform outbound requests to the following endpoints and ports, in addition to endpoints and ports required for basic operation. For more information, see [Allow device traffic through a proxy or firewall](allow-device-traffic.md).


| Endpoint | Port | Required | Description | 
| --- | --- | --- | --- | 
|  `iot.region.amazonaws.com`  | 443 | Yes |  Used to get information about AWS IoT thing certificates.  | 

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#client-device-auth-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

------
#### [ 2.5.5 ]

The following table lists the dependencies for version 2.5.5 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.6.0 <2.17.0 | Soft | 

------
#### [ 2.5.4 ]

The following table lists the dependencies for version 2.5.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.6.0 <2.16.0 | Soft | 

------
#### [ 2.5.2 – 2.5.3 ]

The following table lists the dependencies for versions 2.5.2 and 2.5.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.6.0 <2.15.0 | Soft | 

------
#### [ 2.5.1 ]

The following table lists the dependencies for version 2.5.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.6.0 <2.14.0 | Soft | 

------
#### [ 2.4.4 - 2.5.0 ]

The following table lists the dependencies for version 2.4.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.6.0 <2.13.0 | Soft | 

------
#### [ 2.4.3 ]

The following table lists the dependencies for version 2.4.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.6.0 <2.12.0 | Soft | 

------
#### [ 2.4.1 and 2.4.2 ]

The following table lists the dependencies for version 2.4.1 and 2.4.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.6.0 <2.11.0 | Soft | 

------
#### [ 2.3.0 – 2.4.0 ]

The following table lists the dependencies for versions 2.3.0 to 2.4.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.6.0 <2.10.0 | Soft | 

------
#### [ 2.3.0 ]

The following table lists the dependencies for version 2.3.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.6.0 <2.10.0 | Soft | 

------
#### [ 2.2.3 ]

The following table lists the dependencies for version 2.2.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.6.0 <=2.9.0 | Soft | 

------
#### [ 2.2.2 ]

The following table lists the dependencies for version 2.2.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.6.0 <=2.8.0 | Soft | 

------
#### [ 2.2.1 ]

The following table lists the dependencies for version 2.2.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.6.0 <2.8.0 | Soft | 

------
#### [ 2.2.0 ]

The following table lists the dependencies for version 2.2.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.6.0 <2.7.0 | Soft | 

------
#### [ 2.1.0 ]

The following table lists the dependencies for version 2.1.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.2.0 <2.7.0 | Soft | 

------
#### [ 2.0.4 ]

The following table lists the dependencies for version 2.0.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.2.0 <2.6.0 | Soft | 

------
#### [ 2.0.2 and 2.0.3 ]

The following table lists the dependencies for versions 2.0.2 and 2.0.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.2.0 <2.5.0 | Soft | 

------
#### [ 2.0.1 ]

The following table lists the dependencies for version 2.0.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.2.0 <2.4.0 | Soft | 

------
#### [ 2.0.0 ]

The following table lists the dependencies for version 2.0.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.2.0 <2.3.0 | Soft | 

------

For more information about component dependencies, see the [component recipe reference](component-recipe-reference.md#recipe-reference-component-dependencies).

## Configuration


This component provides the following configuration parameters that you can customize when you deploy the component.

**Note**  
The subscribe permission is evaluated during a client subscribe request to the local MQTT broker. If the client’s existing subscribe permission is revoked, the client will no longer be able to subscribe to a topic. It will, however, continue to receive messages from any previously subscribed topics. To prevent this behavior, the local MQTT broker should be restarted after revoking subscribe permission to force reauthorization of clients.  
For the MQTT 5 broker (EMQX) component, update the `restartIdentifier` configuration to restart the MQTT 5 broker.  
For the MQTT 3.1.1 broker (Moquette) component, it restarts weekly by default when the server certificate changes forcing clients to reauthorize. You can force a restart either by changing the connectivity information (IP addresses) of the core device or by making a deployment to remove the broker component and then deploy it again later.

------
#### [ v2.5.0 – 2.5.4 ]

`deviceGroups`  
Device groups are groups of client devices that have permissions to connect and communicate with a core device. Use selection rules to identify groups of client devices, and define *client device authorization policies* that specify the permissions for each device group.  
This object contains the following information:    
`formatVersion`  
The format version for this configuration object.  
Choose from the following options:  
+ `2021-03-05`  
`definitions`  
The device groups for this core device. Each definition specifies a *selection rule* to evaluate if a client device is a member of the group. Each definition also specifies the permissions policy to apply to client devices that match the selection rule. If a client device is a member of multiple device groups, the device's permissions are comprised of each group's permissions policy.  
This object contains the following information:    
`groupNameKey`  
The name of this device group. Replace *groupNameKey* with a name that helps you identify this device group.  
This object contains the following information:    
`selectionRule`  
The query that specifies which client devices are members of this device group. When a client device connects, the core device evaluates this selection rule to determine if the client device is a member of this device group. If the client device is a member, the core device uses this device group's policy to authorize the client device's actions.  
Each selection rule comprises at least one *selection rule clause*, which is a single expression query that can match client devices. Selection rules use the same query syntax as AWS IoT fleet indexing. For more information about selection rule syntax, see [AWS IoT fleet indexing query syntax](https://docs.aws.amazon.com/iot/latest/developerguide/query-syntax.html) in the *AWS IoT Core Developer Guide*.  
Use the `*` wildcard to match multiple client devices with one selection rule clause. You can use this wildcard at the beginning and end of the thing name to match client devices whose names start or end with the string that you specify. You can also use this wildcard to match all client devices.  
To select a value that contains a colon character (`:`), escape the colon with a backslash character (`\`). In formats such as JSON, you must escape backslash characters, so you enter two backslash characters before the colon character. For example, specify `thingName: MyTeam\\:ClientDevice1` to select a thing whose name is `MyTeam:ClientDevice1`.
You can specify the following selector:  
+ `thingName` – The name of a client device's AWS IoT thing.

**Example selection rule**  
The following selection rule matches client devices whose names are `MyClientDevice1` or `MyClientDevice2`.  

```
thingName: MyClientDevice1 OR thingName: MyClientDevice2
```

**Example selection rule (use wildcards)**  
The following selection rule matches client devices whose names start with `MyClientDevice`.  

```
thingName: MyClientDevice*
```

**Example selection rule (use wildcards)**  
The following selection rule matches client devices whose names end with `MyClientDevice`.  

```
thingName: *MyClientDevice
```

**Example selection rule (match all devices)**  
The following selection rule matches all client devices.  

```
thingName: *
```  
`policyName`  
The permissions policy that applies to client devices in this device group. Specify the name of a policy that you define in the `policies` object.  
`policies`  
The client device authorization policies for client devices that connect to the core device. Each authorization policy specifies a set of actions and the resources where a client device can perform those actions.  
This object contains the following information:    
`policyNameKey`  
The name of this authorization policy. Replace *policyNameKey* with a name that helps you identify this authorization policy. You use this policy name to define which policy applies to a device group.  
This object contains the following information:    
`statementNameKey`  
The name of this policy statement. Replace *statementNameKey* with a name that helps you identify this policy statement.  
This object contains the following information:    
`operations`  
The list of operations to allow for the resources in this policy.  
You can include any of the following operations:  
+ `mqtt:connect` – Grants permission to connect to the core device. Client devices must have this permission to connect to a core device.

  This operation supports the following resources:
  + `mqtt:clientId:deviceClientId` – Restrict access based on the client ID that a client device uses to connect to the core device's MQTT broker. Replace *deviceClientId* with the client ID to use.
+ `mqtt:publish` – Grants permission to publish MQTT messages to topics.

  This operation supports the following resources:
  + <a name="client-device-authorization-policy-resource-mqtt-topic"></a>`mqtt:topic:mqttTopic` – Restrict access based on the MQTT topic where a client device publishes a message. Replace *mqttTopic* with the topic to use.

    This resource doesn't support MQTT topic wildcards.
+ `mqtt:subscribe` – Grants permission to subscribe to MQTT topic filters to receive messages.

  This operation supports the following resources:
  + `mqtt:topicfilter:mqttTopicFilter` – Restrict access based on the MQTT topics where a client device can subscribe to messages. Replace *mqttTopicFilter* with the topic filter to use.

    This resource doesn't support MQTT topic wildcards.  
`resources`  
The list of resources to allow for the operations in this policy. Specify resources that correspond to the operations in this policy. For example, you might specify a list of MQTT topic resources (`mqtt:topic:mqttTopic`) in a policy that specifies the `mqtt:publish` operation.  
You can specify the `*` wildcard anywhere within the resource variable to allow access to all resources. For example, you can specify **mqtt:topic:my\$1** to allow access to resources that match that input.  
The following resource variable is supported:  
+ `mqtt:topic:${iot:Connection.Thing.ThingName}`

  This resolves to the name of the thing in the AWS IoT Core registry for which the policy is being evaluated. AWS IoT Core uses the certificate the device presents when it authenticates to determine which thing to use to verify the connection. This policy variable is only available when a device connects over MQTT or MQTT over the WebSocket protocol.  
`statementDescription`  
(Optional) A description for this policy statement.

`certificates`  <a name="client-device-auth-component-configuration-certificates"></a>
(Optional) The certificate configuration options for this core device. This object contains the following information:    
`serverCertificateValiditySeconds`  
(Optional) The amount of time (in seconds) after which the local MQTT server certificate expires. You can configure this option to customize how often client devices disconnect and reconnect to the core device.  
This component rotates the local MQTT server certificate 24 hours before it expires. The MQTT broker, such as the [Moquette MQTT broker component](mqtt-broker-moquette-component.md), generates a new certificate and restarts. When this happens, all client devices connected to this core device are disconnected. Client devices can reconnect to the core device after a short period of time.  
Default: `604800` (7 days)  
Minimum value: `172800` (2 days)  
Maximum value: `864000` (10 days)

`performance`  
(Optional) The performance configuration options for this core device. This object contains the following information:    
`maxActiveAuthTokens`  
(Optional) The maximum number of active client device authorization tokens. You can increase this number to enable a greater number of client devices to connect to a single core device, without reauthenticating them.  
Default: `2500`  
`cloudRequestQueueSize`  
(Optional) The maximum number of AWS Cloud requests to queue before this component rejects requests.  
Default: `100`  
`maxConcurrentCloudRequests`  
(Optional) The maximum number of concurrent requests to send to the AWS Cloud. You can increase this number to improve authentication performance on core devices where you connect large numbers of client devices.  
Default: `1`

`certificateAuthority`  
(Optional) Certificate authority configuration options to replace the core device intermediate authority with your own intermediate certificate authority.  
If you configure your Greengrass core device with a custom certificate authority (CA) and use the same CA to issue client device certificates, Greengrass bypasses authorization policy checks for client device MQTT operations. The client device auth component fully trusts clients using certificates signed by the CA that it is configured to use.  
To restrict this behavior when using a custom CA, create and sign client devices using a different CA or intermediate CA, then adjust the `certificateUri` and `certificateChainUri` fields to point to the correct intermediate CA.
 This object contains the following information.    
certificateUri  
The location of the certificate. It can be a file system URI or a URI that points to a certificate stored in a hardware security module.  
`certificateChainUri`  
The location of the certificate chain for the core device CA. This should be the complete certificate chain back to your root CA. It can be a file system URI or a URI that points to a certificate chain stored in a hardware security module.  
`privateKeyUri`  
The location of the core device's private key. This can be a file system URI or a URI that points to a certificate private key stored in a hardware security module.

`security`  
(Optional) Security configuration options for this core device. This object contains the following information.    
`clientDeviceTrustDurationMinutes`  
The duration in minutes that the authentication information of a client device can be trusted before it's required to reauthenticate with the core device. The default value is 1.

`metrics`  
(Optional) The metrics options for this core device. Error metrics will only display if there is an error with the client device auth. This object contains the following information:    
`disableMetrics`  
If the `disableMetrics` field is set as `true`, the client device auth won't collect metrics.  
Default: `false`  
`aggregatePeriodSeconds`  
The aggregation period in seconds that determines how often the client device auth aggregates metrics and sends them to the telemetry agent. This doesn't change how often metrics are published because the telemetry agent still publishes them once a day.  
Default: `3600`

startupTimeoutSeconds  
(Optional) The maximum of time in seconds for the component to start. The component's state changes to `ERRORED` if it exceeds this timeout.  
Default: `120`

**Example: Configuration merge update (using a restrictive policy)**  <a name="client-device-auth-component-configuration-example-restrictive"></a>
The following example configuration specifies to allow client devices whose names start with `MyClientDevice` to connect and publish/subscribe on all topics.  

```
{
  "deviceGroups": {
    "formatVersion": "2021-03-05",
    "definitions": {
      "MyDeviceGroup": {
        "selectionRule": "thingName: MyClientDevice*",
        "policyName": "MyRestrictivePolicy"
      }
    },
    "policies": {
      "MyRestrictivePolicy": {
        "AllowConnect": {
          "statementDescription": "Allow client devices to connect.",
          "operations": [
            "mqtt:connect"
          ],
          "resources": [
            "*"
          ]
        },
        "AllowPublish": {
          "statementDescription": "Allow client devices to publish on test/topic.",
          "operations": [
            "mqtt:publish"
          ],
          "resources": [
            "mqtt:topic:test/topic"
          ]
        },
        "AllowSubscribe": {
          "statementDescription": "Allow client devices to subscribe to test/topic/response.",
          "operations": [
            "mqtt:subscribe"
          ],
          "resources": [
            "mqtt:topicfilter:test/topic/response"
          ]
        }
      }
    }
  }
}
```

**Example: Configuration merge update (using a permissive policy)**  <a name="client-device-auth-component-configuration-example-permissive"></a>
The following example configuration specifies to allow all client devices to connect and publish/subscribe on all topics.  

```
{
  "deviceGroups": {
    "formatVersion": "2021-03-05",
    "definitions": {
      "MyPermissiveDeviceGroup": {
        "selectionRule": "thingName: *",
        "policyName": "MyPermissivePolicy"
      }
    },
    "policies": {
      "MyPermissivePolicy": {
        "AllowAll": {
          "statementDescription": "Allow client devices to perform all actions.",
          "operations": [
            "*"
          ],
          "resources": [
            "*"
          ]
        }
      }
    }
  }
}
```

**Example: Configuration merge update (using a thing name policy)**  <a name="client-device-auth-component-configuration-example-mythingname"></a>
The following example configuration enables client devices to publish on topics that begin with the client device's thing name and end with the string `topic`.  

```
{
  "deviceGroups": {
    "formatVersion": "2021-03-05",
    "definitions": {
      "myThing": {
        "selectionRule": "thingName: *",
        "policyName": "MyThingNamePolicy"
      }
    },
    "policies": {
      "MyThingNamePolicy": {
        "policyStatement": {
          "statementDescription": "mqtt publish",
          "operations": [
            "mqtt:publish"
          ],
          "resources": [
            "mqtt:topic:${iot:Connection.Thing.ThingName}/*/topic"
          ]
        }
      }
    }
  }
}
```

------
#### [ v2.4.5 ]

`deviceGroups`  
Device groups are groups of client devices that have permissions to connect and communicate with a core device. Use selection rules to identify groups of client devices, and define *client device authorization policies* that specify the permissions for each device group.  
This object contains the following information:    
`formatVersion`  
The format version for this configuration object.  
Choose from the following options:  
+ `2021-03-05`  
`definitions`  
The device groups for this core device. Each definition specifies a *selection rule* to evaluate if a client device is a member of the group. Each definition also specifies the permissions policy to apply to client devices that match the selection rule. If a client device is a member of multiple device groups, the device's permissions are comprised of each group's permissions policy.  
This object contains the following information:    
`groupNameKey`  
The name of this device group. Replace *groupNameKey* with a name that helps you identify this device group.  
This object contains the following information:    
`selectionRule`  
The query that specifies which client devices are members of this device group. When a client device connects, the core device evaluates this selection rule to determine if the client device is a member of this device group. If the client device is a member, the core device uses this device group's policy to authorize the client device's actions.  
Each selection rule comprises at least one *selection rule clause*, which is a single expression query that can match client devices. Selection rules use the same query syntax as AWS IoT fleet indexing. For more information about selection rule syntax, see [AWS IoT fleet indexing query syntax](https://docs.aws.amazon.com/iot/latest/developerguide/query-syntax.html) in the *AWS IoT Core Developer Guide*.  
Use the `*` wildcard to match multiple client devices with one selection rule clause. You can use this wildcard at the beginning and end of the thing name to match client devices whose names start or end with the string that you specify. You can also use this wildcard to match all client devices.  
To select a value that contains a colon character (`:`), escape the colon with a backslash character (`\`). In formats such as JSON, you must escape backslash characters, so you enter two backslash characters before the colon character. For example, specify `thingName: MyTeam\\:ClientDevice1` to select a thing whose name is `MyTeam:ClientDevice1`.
You can specify the following selector:  
+ `thingName` – The name of a client device's AWS IoT thing.

**Example selection rule**  
The following selection rule matches client devices whose names are `MyClientDevice1` or `MyClientDevice2`.  

```
thingName: MyClientDevice1 OR thingName: MyClientDevice2
```

**Example selection rule (use wildcards)**  
The following selection rule matches client devices whose names start with `MyClientDevice`.  

```
thingName: MyClientDevice*
```

**Example selection rule (use wildcards)**  
The following selection rule matches client devices whose names end with `MyClientDevice`.  

```
thingName: *MyClientDevice
```

**Example selection rule (match all devices)**  
The following selection rule matches all client devices.  

```
thingName: *
```  
`policyName`  
The permissions policy that applies to client devices in this device group. Specify the name of a policy that you define in the `policies` object.  
`policies`  
The client device authorization policies for client devices that connect to the core device. Each authorization policy specifies a set of actions and the resources where a client device can perform those actions.  
This object contains the following information:    
`policyNameKey`  
The name of this authorization policy. Replace *policyNameKey* with a name that helps you identify this authorization policy. You use this policy name to define which policy applies to a device group.  
This object contains the following information:    
`statementNameKey`  
The name of this policy statement. Replace *statementNameKey* with a name that helps you identify this policy statement.  
This object contains the following information:    
`operations`  
The list of operations to allow for the resources in this policy.  
You can include any of the following operations:  
+ `mqtt:connect` – Grants permission to connect to the core device. Client devices must have this permission to connect to a core device.

  This operation supports the following resources:
  + `mqtt:clientId:deviceClientId` – Restrict access based on the client ID that a client device uses to connect to the core device's MQTT broker. Replace *deviceClientId* with the client ID to use.
+ `mqtt:publish` – Grants permission to publish MQTT messages to topics.

  This operation supports the following resources:
  + <a name="client-device-authorization-policy-resource-mqtt-topic"></a>`mqtt:topic:mqttTopic` – Restrict access based on the MQTT topic where a client device publishes a message. Replace *mqttTopic* with the topic to use.

    This resource doesn't support MQTT topic wildcards.
+ `mqtt:subscribe` – Grants permission to subscribe to MQTT topic filters to receive messages.

  This operation supports the following resources:
  + <a name="client-device-authorization-policy-resource-mqtt-topicfilter"></a>`mqtt:topicfilter:mqttTopicFilter` – Restrict access based on the MQTT topics where a client device can subscribe to messages. Replace *mqttTopicFilter* with the topic filter to use.

    This resource supports the `+` and `#` MQTT topic wildcards. For more information, see [MQTT topics](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html) in the *AWS IoT Core Developer Guide*.

    The client device can subscribe to the exact topic filters that you allow. For example, if you allow the client device to subscribe to the `mqtt:topicfilter:client/+/status` resource, the client device can subscribe to `client/+/status` but not `client/client1/status`.
You can specify the `*` wildcard to allow access to all actions.  
`resources`  
The list of resources to allow for the operations in this policy. Specify resources that correspond to the operations in this policy. For example, you might specify a list of MQTT topic resources (`mqtt:topic:mqttTopic`) in a policy that specifies the `mqtt:publish` operation.  
You can specify the `*` wildcard to allow access to all resources. You can't use the `*` wildcard to match partial resource identifiers. For example, you can specify **"resources": "\$1"**, but you can't specify **"resources": "mqtt:clientId:\$1"**.  
`statementDescription`  
(Optional) A description for this policy statement.

`certificates`  <a name="client-device-auth-component-configuration-certificates"></a>
(Optional) The certificate configuration options for this core device. This object contains the following information:    
`serverCertificateValiditySeconds`  
(Optional) The amount of time (in seconds) after which the local MQTT server certificate expires. You can configure this option to customize how often client devices disconnect and reconnect to the core device.  
This component rotates the local MQTT server certificate 24 hours before it expires. The MQTT broker, such as the [Moquette MQTT broker component](mqtt-broker-moquette-component.md), generates a new certificate and restarts. When this happens, all client devices connected to this core device are disconnected. Client devices can reconnect to the core device after a short period of time.  
Default: `604800` (7 days)  
Minimum value: `172800` (2 days)  
Maximum value: `864000` (10 days)

`performance`  
(Optional) The performance configuration options for this core device. This object contains the following information:    
`maxActiveAuthTokens`  
(Optional) The maximum number of active client device authorization tokens. You can increase this number to enable a greater number of client devices to connect to a single core device, without reauthenticating them.  
Default: `2500`  
`cloudRequestQueueSize`  
(Optional) The maximum number of AWS Cloud requests to queue before this component rejects requests.  
Default: `100`  
`maxConcurrentCloudRequests`  
(Optional) The maximum number of concurrent requests to send to the AWS Cloud. You can increase this number to improve authentication performance on core devices where you connect large numbers of client devices.  
Default: `1`

`certificateAuthority`  
(Optional) Certificate authority configuration options to replace the core device intermediate authority with your own intermediate certificate authority.  
If you configure your Greengrass core device with a custom certificate authority (CA) and use the same CA to issue client device certificates, Greengrass bypasses authorization policy checks for client device MQTT operations. The client device auth component fully trusts clients using certificates signed by the CA that it is configured to use.  
To restrict this behavior when using a custom CA, create and sign client devices using a different CA or intermediate CA, then adjust the `certificateUri` and `certificateChainUri` fields to point to the correct intermediate CA.
 This object contains the following information.    
certificateUri  
The location of the certificate. It can be a file system URI or a URI that points to a certificate stored in a hardware security module.  
`certificateChainUri`  
The location of the certificate chain for the core device CA. This should be the complete certificate chain back to your root CA. It can be a file system URI or a URI that points to a certificate chain stored in a hardware security module.  
`privateKeyUri`  
The location of the core device's private key. This can be a file system URI or a URI that points to a certificate private key stored in a hardware security module.

`security`  
(Optional) Security configuration options for this core device. This object contains the following information.    
`clientDeviceTrustDurationMinutes`  
The duration in minutes that the authentication information of a client device can be trusted before it's required to reauthenticate with the core device. The default value is 1.

`metrics`  
(Optional) The metrics options for this core device. Error metrics will only display if there is an error with the client device auth. This object contains the following information:    
`disableMetrics`  
If the `disableMetrics` field is set as `true`, the client device auth won't collect metrics.  
Default: `false`  
`aggregatePeriodSeconds`  
The aggregation period in seconds that determines how often the client device auth aggregates metrics and sends them to the telemetry agent. This doesn't change how often metrics are published because the telemetry agent still publishes them once a day.  
Default: `3600`

startupTimeoutSeconds  
(Optional) The maximum of time in seconds for the component to start. The component's state changes to `ERRORED` if it exceeds this timeout.  
Default: `120`

**Example: Configuration merge update (using a restrictive policy)**  <a name="client-device-auth-component-configuration-example-restrictive"></a>
The following example configuration specifies to allow client devices whose names start with `MyClientDevice` to connect and publish/subscribe on all topics.  

```
{
  "deviceGroups": {
    "formatVersion": "2021-03-05",
    "definitions": {
      "MyDeviceGroup": {
        "selectionRule": "thingName: MyClientDevice*",
        "policyName": "MyRestrictivePolicy"
      }
    },
    "policies": {
      "MyRestrictivePolicy": {
        "AllowConnect": {
          "statementDescription": "Allow client devices to connect.",
          "operations": [
            "mqtt:connect"
          ],
          "resources": [
            "*"
          ]
        },
        "AllowPublish": {
          "statementDescription": "Allow client devices to publish on test/topic.",
          "operations": [
            "mqtt:publish"
          ],
          "resources": [
            "mqtt:topic:test/topic"
          ]
        },
        "AllowSubscribe": {
          "statementDescription": "Allow client devices to subscribe to test/topic/response.",
          "operations": [
            "mqtt:subscribe"
          ],
          "resources": [
            "mqtt:topicfilter:test/topic/response"
          ]
        }
      }
    }
  }
}
```

**Example: Configuration merge update (using a permissive policy)**  <a name="client-device-auth-component-configuration-example-permissive"></a>
The following example configuration specifies to allow all client devices to connect and publish/subscribe on all topics.  

```
{
  "deviceGroups": {
    "formatVersion": "2021-03-05",
    "definitions": {
      "MyPermissiveDeviceGroup": {
        "selectionRule": "thingName: *",
        "policyName": "MyPermissivePolicy"
      }
    },
    "policies": {
      "MyPermissivePolicy": {
        "AllowAll": {
          "statementDescription": "Allow client devices to perform all actions.",
          "operations": [
            "*"
          ],
          "resources": [
            "*"
          ]
        }
      }
    }
  }
}
```

------
#### [ v2.4.2 - v2.4.4 ]

`deviceGroups`  <a name="client-device-auth-component-configuration-devicegroups"></a>
Device groups are groups of client devices that have permissions to connect and communicate with a core device. Use selection rules to identify groups of client devices, and define *client device authorization policies* that specify the permissions for each device group.  
This object contains the following information:    
`formatVersion`  
The format version for this configuration object.  
Choose from the following options:  
+ `2021-03-05`  
`definitions`  
The device groups for this core device. Each definition specifies a *selection rule* to evaluate if a client device is a member of the group. Each definition also specifies the permissions policy to apply to client devices that match the selection rule. If a client device is a member of multiple device groups, the device's permissions are comprised of each group's permissions policy.  
This object contains the following information:    
`groupNameKey`  
The name of this device group. Replace *groupNameKey* with a name that helps you identify this device group.  
This object contains the following information:    
`selectionRule`  
The query that specifies which client devices are members of this device group. When a client device connects, the core device evaluates this selection rule to determine if the client device is a member of this device group. If the client device is a member, the core device uses this device group's policy to authorize the client device's actions.  
Each selection rule comprises at least one *selection rule clause*, which is a single expression query that can match client devices. Selection rules use the same query syntax as AWS IoT fleet indexing. For more information about selection rule syntax, see [AWS IoT fleet indexing query syntax](https://docs.aws.amazon.com/iot/latest/developerguide/query-syntax.html) in the *AWS IoT Core Developer Guide*.  
Use the `*` wildcard to match multiple client devices with one selection rule clause. You can use this wildcard at the end of the thing name to match client devices whose names start with a string that you specify. You can also use this wildcard to match all client devices.  
To select a value that contains a colon character (`:`), escape the colon with a backslash character (`\\`). In formats such as JSON, you must escape backslash characters, so you enter two backslash characters before the colon character. For example, specify `thingName: MyTeam\\\\:ClientDevice1` to select a thing whose name is `MyTeam:ClientDevice1`.
You can specify the following selector:  
+ `thingName` – The name of a client device's AWS IoT thing.

**Example selection rule**  
The following selection rule matches client devices whose names are `MyClientDevice1` or `MyClientDevice2`.  

```
thingName: MyClientDevice1 OR thingName: MyClientDevice2
```

**Example selection rule (use wildcards)**  
The following selection rule matches client devices whose names start with `MyClientDevice`.  

```
thingName: MyClientDevice*
```

**Example selection rule (match all devices)**  
The following selection rule matches all client devices.  

```
thingName: *
```  
`policyName`  
The permissions policy that applies to client devices in this device group. Specify the name of a policy that you define in the `policies` object.  
`policies`  
The client device authorization policies for client devices that connect to the core device. Each authorization policy specifies a set of actions and the resources where a client device can perform those actions.  
This object contains the following information:    
`policyNameKey`  
The name of this authorization policy. Replace *policyNameKey* with a name that helps you identify this authorization policy. You use this policy name to define which policy applies to a device group.  
This object contains the following information:    
`statementNameKey`  
The name of this policy statement. Replace *statementNameKey* with a name that helps you identify this policy statement.  
This object contains the following information:    
`operations`  
The list of operations to allow for the resources in this policy.  
You can include any of the following operations:  
+ `mqtt:connect` – Grants permission to connect to the core device. Client devices must have this permission to connect to a core device.

  This operation supports the following resources:
  + `mqtt:clientId:deviceClientId` – Restrict access based on the client ID that a client device uses to connect to the core device's MQTT broker. Replace *deviceClientId* with the client ID to use.
+ `mqtt:publish` – Grants permission to publish MQTT messages to topics.

  This operation supports the following resources:
  + <a name="client-device-authorization-policy-resource-mqtt-topic"></a>`mqtt:topic:mqttTopic` – Restrict access based on the MQTT topic where a client device publishes a message. Replace *mqttTopic* with the topic to use.

    This resource doesn't support MQTT topic wildcards.
+ `mqtt:subscribe` – Grants permission to subscribe to MQTT topic filters to receive messages.

  This operation supports the following resources:
  + <a name="client-device-authorization-policy-resource-mqtt-topicfilter"></a>`mqtt:topicfilter:mqttTopicFilter` – Restrict access based on the MQTT topics where a client device can subscribe to messages. Replace *mqttTopicFilter* with the topic filter to use.

    This resource supports the `+` and `#` MQTT topic wildcards. For more information, see [MQTT topics](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html) in the *AWS IoT Core Developer Guide*.

    The client device can subscribe to the exact topic filters that you allow. For example, if you allow the client device to subscribe to the `mqtt:topicfilter:client/+/status` resource, the client device can subscribe to `client/+/status` but not `client/client1/status`.
You can specify the `*` wildcard to allow access to all actions.  
`resources`  
The list of resources to allow for the operations in this policy. Specify resources that correspond to the operations in this policy. For example, you might specify a list of MQTT topic resources (`mqtt:topic:mqttTopic`) in a policy that specifies the `mqtt:publish` operation.  
You can specify the `*` wildcard to allow access to all resources. You can't use the `*` wildcard to match partial resource identifiers. For example, you can specify **"resources": "\$1"**, but you can't specify **"resources": "mqtt:clientId:\$1"**.  
`statementDescription`  
(Optional) A description for this policy statement.

`certificates`  <a name="client-device-auth-component-configuration-certificates"></a>
(Optional) The certificate configuration options for this core device. This object contains the following information:    
`serverCertificateValiditySeconds`  
(Optional) The amount of time (in seconds) after which the local MQTT server certificate expires. You can configure this option to customize how often client devices disconnect and reconnect to the core device.  
This component rotates the local MQTT server certificate 24 hours before it expires. The MQTT broker, such as the [Moquette MQTT broker component](mqtt-broker-moquette-component.md), generates a new certificate and restarts. When this happens, all client devices connected to this core device are disconnected. Client devices can reconnect to the core device after a short period of time.  
Default: `604800` (7 days)  
Minimum value: `172800` (2 days)  
Maximum value: `864000` (10 days)

`performance`  
(Optional) The performance configuration options for this core device. This object contains the following information:    
`maxActiveAuthTokens`  
(Optional) The maximum number of active client device authorization tokens. You can increase this number to enable a greater number of client devices to connect to a single core device, without reauthenticating them.  
Default: `2500`  
`cloudRequestQueueSize`  
(Optional) The maximum number of AWS Cloud requests to queue before this component rejects requests.  
Default: `100`  
`maxConcurrentCloudRequests`  
(Optional) The maximum number of concurrent requests to send to the AWS Cloud. You can increase this number to improve authentication performance on core devices where you connect large numbers of client devices.  
Default: `1`

`certificateAuthority`  
(Optional) Certificate authority configuration options to replace the core device intermediate authority with your own intermediate certificate authority.  
If you configure your Greengrass core device with a custom certificate authority (CA) and use the same CA to issue client device certificates, Greengrass bypasses authorization policy checks for client device MQTT operations. The client device auth component fully trusts clients using certificates signed by the CA that it is configured to use.  
To restrict this behavior when using a custom CA, create and sign client devices using a different CA or intermediate CA, then adjust the `certificateUri` and `certificateChainUri` fields to point to the correct intermediate CA.
 This object contains the following information.    
certificateUri  
The location of the certificate. It can be a file system URI or a URI that points to a certificate stored in a hardware security module.  
`certificateChainUri`  
The location of the certificate chain for the core device CA. This should be the complete certificate chain back to your root CA. It can be a file system URI or a URI that points to a certificate chain stored in a hardware security module.  
`privateKeyUri`  
The location of the core device's private key. This can be a file system URI or a URI that points to a certificate private key stored in a hardware security module.

`security`  
(Optional) Security configuration options for this core device. This object contains the following information.    
`clientDeviceTrustDurationMinutes`  
The duration in minutes that the authentication information of a client device can be trusted before it's required to reauthenticate with the core device. The default value is 1.

`metrics`  
(Optional) The metrics options for this core device. Error metrics will only display if there is an error with the client device auth. This object contains the following information:    
`disableMetrics`  
If the `disableMetrics` field is set as `true`, the client device auth won't collect metrics.  
Default: `false`  
`aggregatePeriodSeconds`  
The aggregation period in seconds that determines how often the client device auth aggregates metrics and sends them to the telemetry agent. This doesn't change how often metrics are published because the telemetry agent still publishes them once a day.  
Default: `3600`

startupTimeoutSeconds  
(Optional) The maximum of time in seconds for the component to start. The component's state changes to `ERRORED` if it exceeds this timeout.  
Default: `120`

**Example: Configuration merge update (using a restrictive policy)**  <a name="client-device-auth-component-configuration-example-restrictive"></a>
The following example configuration specifies to allow client devices whose names start with `MyClientDevice` to connect and publish/subscribe on all topics.  

```
{
  "deviceGroups": {
    "formatVersion": "2021-03-05",
    "definitions": {
      "MyDeviceGroup": {
        "selectionRule": "thingName: MyClientDevice*",
        "policyName": "MyRestrictivePolicy"
      }
    },
    "policies": {
      "MyRestrictivePolicy": {
        "AllowConnect": {
          "statementDescription": "Allow client devices to connect.",
          "operations": [
            "mqtt:connect"
          ],
          "resources": [
            "*"
          ]
        },
        "AllowPublish": {
          "statementDescription": "Allow client devices to publish on test/topic.",
          "operations": [
            "mqtt:publish"
          ],
          "resources": [
            "mqtt:topic:test/topic"
          ]
        },
        "AllowSubscribe": {
          "statementDescription": "Allow client devices to subscribe to test/topic/response.",
          "operations": [
            "mqtt:subscribe"
          ],
          "resources": [
            "mqtt:topicfilter:test/topic/response"
          ]
        }
      }
    }
  }
}
```

**Example: Configuration merge update (using a permissive policy)**  <a name="client-device-auth-component-configuration-example-permissive"></a>
The following example configuration specifies to allow all client devices to connect and publish/subscribe on all topics.  

```
{
  "deviceGroups": {
    "formatVersion": "2021-03-05",
    "definitions": {
      "MyPermissiveDeviceGroup": {
        "selectionRule": "thingName: *",
        "policyName": "MyPermissivePolicy"
      }
    },
    "policies": {
      "MyPermissivePolicy": {
        "AllowAll": {
          "statementDescription": "Allow client devices to perform all actions.",
          "operations": [
            "*"
          ],
          "resources": [
            "*"
          ]
        }
      }
    }
  }
}
```

------
#### [ v2.4.0 - v2.4.1 ]

`deviceGroups`  <a name="client-device-auth-component-configuration-devicegroups"></a>
Device groups are groups of client devices that have permissions to connect and communicate with a core device. Use selection rules to identify groups of client devices, and define *client device authorization policies* that specify the permissions for each device group.  
This object contains the following information:    
`formatVersion`  
The format version for this configuration object.  
Choose from the following options:  
+ `2021-03-05`  
`definitions`  
The device groups for this core device. Each definition specifies a *selection rule* to evaluate if a client device is a member of the group. Each definition also specifies the permissions policy to apply to client devices that match the selection rule. If a client device is a member of multiple device groups, the device's permissions are comprised of each group's permissions policy.  
This object contains the following information:    
`groupNameKey`  
The name of this device group. Replace *groupNameKey* with a name that helps you identify this device group.  
This object contains the following information:    
`selectionRule`  
The query that specifies which client devices are members of this device group. When a client device connects, the core device evaluates this selection rule to determine if the client device is a member of this device group. If the client device is a member, the core device uses this device group's policy to authorize the client device's actions.  
Each selection rule comprises at least one *selection rule clause*, which is a single expression query that can match client devices. Selection rules use the same query syntax as AWS IoT fleet indexing. For more information about selection rule syntax, see [AWS IoT fleet indexing query syntax](https://docs.aws.amazon.com/iot/latest/developerguide/query-syntax.html) in the *AWS IoT Core Developer Guide*.  
Use the `*` wildcard to match multiple client devices with one selection rule clause. You can use this wildcard at the end of the thing name to match client devices whose names start with a string that you specify. You can also use this wildcard to match all client devices.  
To select a value that contains a colon character (`:`), escape the colon with a backslash character (`\\`). In formats such as JSON, you must escape backslash characters, so you enter two backslash characters before the colon character. For example, specify `thingName: MyTeam\\\\:ClientDevice1` to select a thing whose name is `MyTeam:ClientDevice1`.
You can specify the following selector:  
+ `thingName` – The name of a client device's AWS IoT thing.

**Example selection rule**  
The following selection rule matches client devices whose names are `MyClientDevice1` or `MyClientDevice2`.  

```
thingName: MyClientDevice1 OR thingName: MyClientDevice2
```

**Example selection rule (use wildcards)**  
The following selection rule matches client devices whose names start with `MyClientDevice`.  

```
thingName: MyClientDevice*
```

**Example selection rule (match all devices)**  
The following selection rule matches all client devices.  

```
thingName: *
```  
`policyName`  
The permissions policy that applies to client devices in this device group. Specify the name of a policy that you define in the `policies` object.  
`policies`  
The client device authorization policies for client devices that connect to the core device. Each authorization policy specifies a set of actions and the resources where a client device can perform those actions.  
This object contains the following information:    
`policyNameKey`  
The name of this authorization policy. Replace *policyNameKey* with a name that helps you identify this authorization policy. You use this policy name to define which policy applies to a device group.  
This object contains the following information:    
`statementNameKey`  
The name of this policy statement. Replace *statementNameKey* with a name that helps you identify this policy statement.  
This object contains the following information:    
`operations`  
The list of operations to allow for the resources in this policy.  
You can include any of the following operations:  
+ `mqtt:connect` – Grants permission to connect to the core device. Client devices must have this permission to connect to a core device.

  This operation supports the following resources:
  + `mqtt:clientId:deviceClientId` – Restrict access based on the client ID that a client device uses to connect to the core device's MQTT broker. Replace *deviceClientId* with the client ID to use.
+ `mqtt:publish` – Grants permission to publish MQTT messages to topics.

  This operation supports the following resources:
  + <a name="client-device-authorization-policy-resource-mqtt-topic"></a>`mqtt:topic:mqttTopic` – Restrict access based on the MQTT topic where a client device publishes a message. Replace *mqttTopic* with the topic to use.

    This resource doesn't support MQTT topic wildcards.
+ `mqtt:subscribe` – Grants permission to subscribe to MQTT topic filters to receive messages.

  This operation supports the following resources:
  + <a name="client-device-authorization-policy-resource-mqtt-topicfilter"></a>`mqtt:topicfilter:mqttTopicFilter` – Restrict access based on the MQTT topics where a client device can subscribe to messages. Replace *mqttTopicFilter* with the topic filter to use.

    This resource supports the `+` and `#` MQTT topic wildcards. For more information, see [MQTT topics](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html) in the *AWS IoT Core Developer Guide*.

    The client device can subscribe to the exact topic filters that you allow. For example, if you allow the client device to subscribe to the `mqtt:topicfilter:client/+/status` resource, the client device can subscribe to `client/+/status` but not `client/client1/status`.
You can specify the `*` wildcard to allow access to all actions.  
`resources`  
The list of resources to allow for the operations in this policy. Specify resources that correspond to the operations in this policy. For example, you might specify a list of MQTT topic resources (`mqtt:topic:mqttTopic`) in a policy that specifies the `mqtt:publish` operation.  
You can specify the `*` wildcard to allow access to all resources. You can't use the `*` wildcard to match partial resource identifiers. For example, you can specify **"resources": "\$1"**, but you can't specify **"resources": "mqtt:clientId:\$1"**.  
`statementDescription`  
(Optional) A description for this policy statement.

`certificates`  <a name="client-device-auth-component-configuration-certificates"></a>
(Optional) The certificate configuration options for this core device. This object contains the following information:    
`serverCertificateValiditySeconds`  
(Optional) The amount of time (in seconds) after which the local MQTT server certificate expires. You can configure this option to customize how often client devices disconnect and reconnect to the core device.  
This component rotates the local MQTT server certificate 24 hours before it expires. The MQTT broker, such as the [Moquette MQTT broker component](mqtt-broker-moquette-component.md), generates a new certificate and restarts. When this happens, all client devices connected to this core device are disconnected. Client devices can reconnect to the core device after a short period of time.  
Default: `604800` (7 days)  
Minimum value: `172800` (2 days)  
Maximum value: `864000` (10 days)

`performance`  
(Optional) The performance configuration options for this core device. This object contains the following information:    
`maxActiveAuthTokens`  
(Optional) The maximum number of active client device authorization tokens. You can increase this number to enable a greater number of client devices to connect to a single core device, without reauthenticating them.  
Default: `2500`  
`cloudRequestQueueSize`  
(Optional) The maximum number of AWS Cloud requests to queue before this component rejects requests.  
Default: `100`  
`maxConcurrentCloudRequests`  
(Optional) The maximum number of concurrent requests to send to the AWS Cloud. You can increase this number to improve authentication performance on core devices where you connect large numbers of client devices.  
Default: `1`

`certificateAuthority`  
(Optional) Certificate authority configuration options to replace the core device intermediate authority with your own intermediate certificate authority. This object contains the following information.  
 This object contains the following information:    
certificateUri  
The location of the certificate. It can be a file system URI or a URI that points to a certificate stored in a hardware security module.  
`certificateChainUri`  
The location of the certificate chain for the core device CA. This should be the complete certificate chain back to your root CA. It can be a file system URI or a URI that points to a certificate chain stored in a hardware security module.  
`privateKeyUri`  
The location of the core device's private key. This can be a file system URI or a URI that points to a certificate private key stored in a hardware security module.

`security`  
(Optional) Security configuration options for this core device. This object contains the following information.    
`clientDeviceTrustDurationMinutes`  
The duration in minutes that the authentication information of a client device can be trusted before it's required to reauthenticate with the core device. The default value is 1.

`metrics`  
(Optional) The metrics options for this core device. Error metrics will only display if there is an error with the client device auth. This object contains the following information:    
`disableMetrics`  
If the `disableMetrics` field is set as `true`, the client device auth won't collect metrics.  
Default: `false`  
`aggregatePeriodSeconds`  
The aggregation period in seconds that determines how often the client device auth aggregates metrics and sends them to the telemetry agent. This doesn't change how often metrics are published because the telemetry agent still publishes them once a day.  
Default: `3600`

**Example: Configuration merge update (using a restrictive policy)**  <a name="client-device-auth-component-configuration-example-restrictive"></a>
The following example configuration specifies to allow client devices whose names start with `MyClientDevice` to connect and publish/subscribe on all topics.  

```
{
  "deviceGroups": {
    "formatVersion": "2021-03-05",
    "definitions": {
      "MyDeviceGroup": {
        "selectionRule": "thingName: MyClientDevice*",
        "policyName": "MyRestrictivePolicy"
      }
    },
    "policies": {
      "MyRestrictivePolicy": {
        "AllowConnect": {
          "statementDescription": "Allow client devices to connect.",
          "operations": [
            "mqtt:connect"
          ],
          "resources": [
            "*"
          ]
        },
        "AllowPublish": {
          "statementDescription": "Allow client devices to publish on test/topic.",
          "operations": [
            "mqtt:publish"
          ],
          "resources": [
            "mqtt:topic:test/topic"
          ]
        },
        "AllowSubscribe": {
          "statementDescription": "Allow client devices to subscribe to test/topic/response.",
          "operations": [
            "mqtt:subscribe"
          ],
          "resources": [
            "mqtt:topicfilter:test/topic/response"
          ]
        }
      }
    }
  }
}
```

**Example: Configuration merge update (using a permissive policy)**  <a name="client-device-auth-component-configuration-example-permissive"></a>
The following example configuration specifies to allow all client devices to connect and publish/subscribe on all topics.  

```
{
  "deviceGroups": {
    "formatVersion": "2021-03-05",
    "definitions": {
      "MyPermissiveDeviceGroup": {
        "selectionRule": "thingName: *",
        "policyName": "MyPermissivePolicy"
      }
    },
    "policies": {
      "MyPermissivePolicy": {
        "AllowAll": {
          "statementDescription": "Allow client devices to perform all actions.",
          "operations": [
            "*"
          ],
          "resources": [
            "*"
          ]
        }
      }
    }
  }
}
```

------
#### [ v2.3.x ]

`deviceGroups`  <a name="client-device-auth-component-configuration-devicegroups"></a>
Device groups are groups of client devices that have permissions to connect and communicate with a core device. Use selection rules to identify groups of client devices, and define *client device authorization policies* that specify the permissions for each device group.  
This object contains the following information:    
`formatVersion`  
The format version for this configuration object.  
Choose from the following options:  
+ `2021-03-05`  
`definitions`  
The device groups for this core device. Each definition specifies a *selection rule* to evaluate if a client device is a member of the group. Each definition also specifies the permissions policy to apply to client devices that match the selection rule. If a client device is a member of multiple device groups, the device's permissions are comprised of each group's permissions policy.  
This object contains the following information:    
`groupNameKey`  
The name of this device group. Replace *groupNameKey* with a name that helps you identify this device group.  
This object contains the following information:    
`selectionRule`  
The query that specifies which client devices are members of this device group. When a client device connects, the core device evaluates this selection rule to determine if the client device is a member of this device group. If the client device is a member, the core device uses this device group's policy to authorize the client device's actions.  
Each selection rule comprises at least one *selection rule clause*, which is a single expression query that can match client devices. Selection rules use the same query syntax as AWS IoT fleet indexing. For more information about selection rule syntax, see [AWS IoT fleet indexing query syntax](https://docs.aws.amazon.com/iot/latest/developerguide/query-syntax.html) in the *AWS IoT Core Developer Guide*.  
Use the `*` wildcard to match multiple client devices with one selection rule clause. You can use this wildcard at the end of the thing name to match client devices whose names start with a string that you specify. You can also use this wildcard to match all client devices.  
To select a value that contains a colon character (`:`), escape the colon with a backslash character (`\\`). In formats such as JSON, you must escape backslash characters, so you enter two backslash characters before the colon character. For example, specify `thingName: MyTeam\\\\:ClientDevice1` to select a thing whose name is `MyTeam:ClientDevice1`.
You can specify the following selector:  
+ `thingName` – The name of a client device's AWS IoT thing.

**Example selection rule**  
The following selection rule matches client devices whose names are `MyClientDevice1` or `MyClientDevice2`.  

```
thingName: MyClientDevice1 OR thingName: MyClientDevice2
```

**Example selection rule (use wildcards)**  
The following selection rule matches client devices whose names start with `MyClientDevice`.  

```
thingName: MyClientDevice*
```

**Example selection rule (match all devices)**  
The following selection rule matches all client devices.  

```
thingName: *
```  
`policyName`  
The permissions policy that applies to client devices in this device group. Specify the name of a policy that you define in the `policies` object.  
`policies`  
The client device authorization policies for client devices that connect to the core device. Each authorization policy specifies a set of actions and the resources where a client device can perform those actions.  
This object contains the following information:    
`policyNameKey`  
The name of this authorization policy. Replace *policyNameKey* with a name that helps you identify this authorization policy. You use this policy name to define which policy applies to a device group.  
This object contains the following information:    
`statementNameKey`  
The name of this policy statement. Replace *statementNameKey* with a name that helps you identify this policy statement.  
This object contains the following information:    
`operations`  
The list of operations to allow for the resources in this policy.  
You can include any of the following operations:  
+ `mqtt:connect` – Grants permission to connect to the core device. Client devices must have this permission to connect to a core device.

  This operation supports the following resources:
  + `mqtt:clientId:deviceClientId` – Restrict access based on the client ID that a client device uses to connect to the core device's MQTT broker. Replace *deviceClientId* with the client ID to use.
+ `mqtt:publish` – Grants permission to publish MQTT messages to topics.

  This operation supports the following resources:
  + <a name="client-device-authorization-policy-resource-mqtt-topic"></a>`mqtt:topic:mqttTopic` – Restrict access based on the MQTT topic where a client device publishes a message. Replace *mqttTopic* with the topic to use.

    This resource doesn't support MQTT topic wildcards.
+ `mqtt:subscribe` – Grants permission to subscribe to MQTT topic filters to receive messages.

  This operation supports the following resources:
  + <a name="client-device-authorization-policy-resource-mqtt-topicfilter"></a>`mqtt:topicfilter:mqttTopicFilter` – Restrict access based on the MQTT topics where a client device can subscribe to messages. Replace *mqttTopicFilter* with the topic filter to use.

    This resource supports the `+` and `#` MQTT topic wildcards. For more information, see [MQTT topics](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html) in the *AWS IoT Core Developer Guide*.

    The client device can subscribe to the exact topic filters that you allow. For example, if you allow the client device to subscribe to the `mqtt:topicfilter:client/+/status` resource, the client device can subscribe to `client/+/status` but not `client/client1/status`.
You can specify the `*` wildcard to allow access to all actions.  
`resources`  
The list of resources to allow for the operations in this policy. Specify resources that correspond to the operations in this policy. For example, you might specify a list of MQTT topic resources (`mqtt:topic:mqttTopic`) in a policy that specifies the `mqtt:publish` operation.  
You can specify the `*` wildcard to allow access to all resources. You can't use the `*` wildcard to match partial resource identifiers. For example, you can specify **"resources": "\$1"**, but you can't specify **"resources": "mqtt:clientId:\$1"**.  
`statementDescription`  
(Optional) A description for this policy statement.

`certificates`  <a name="client-device-auth-component-configuration-certificates"></a>
(Optional) The certificate configuration options for this core device. This object contains the following information:    
`serverCertificateValiditySeconds`  
(Optional) The amount of time (in seconds) after which the local MQTT server certificate expires. You can configure this option to customize how often client devices disconnect and reconnect to the core device.  
This component rotates the local MQTT server certificate 24 hours before it expires. The MQTT broker, such as the [Moquette MQTT broker component](mqtt-broker-moquette-component.md), generates a new certificate and restarts. When this happens, all client devices connected to this core device are disconnected. Client devices can reconnect to the core device after a short period of time.  
Default: `604800` (7 days)  
Minimum value: `172800` (2 days)  
Maximum value: `864000` (10 days)

`performance`  
(Optional) The performance configuration options for this core device. This object contains the following information:    
`maxActiveAuthTokens`  
(Optional) The maximum number of active client device authorization tokens. You can increase this number to enable a greater number of client devices to connect to a single core device without reauthenticating them.  
Default: `2500`  
`cloudRequestQueueSize`  
(Optional) The maximum number of AWS Cloud requests to queue before this component rejects requests.  
Default: `100`  
`maxConcurrentCloudRequests`  
(Optional) The maximum number of concurrent requests to send to the AWS Cloud. You can increase this number to improve authentication performance on core devices where you connect large numbers of client devices.  
Default: `1`

`certificateAuthority`  
(Optional) Certificate authority configuration options to replace the core device intermediate authority with your own intermediate certificate authority. This object contains the following information.    
certificateUri  
The location of the certificate. It can be a file system URI or a URI that points to a certificate stored in a hardware security module.  
`certificateChainUri`  
The location of the certificate chain for the core device CA. This should be the complete certificate chain back to your root CA. It can be a file system URI or a URI that points to a certificate chain stored in a hardware security module.  
`privateKeyUri`  
The location of the core device's private key. This can be a file system URI or a URI that points to a certificate private key stored in a hardware security module.

`security`  
(Optional) Security configuration options for this core device. This object contains the following information.    
`clientDeviceTrustDurationMinutes`  
The duration in minutes that the authentication information of a client device can be trusted before it is required to reauthenticate with the core device. The default value is 1.

**Example: Configuration merge update (using a restrictive policy)**  <a name="client-device-auth-component-configuration-example-restrictive"></a>
The following example configuration specifies to allow client devices whose names start with `MyClientDevice` to connect and publish/subscribe on all topics.  

```
{
  "deviceGroups": {
    "formatVersion": "2021-03-05",
    "definitions": {
      "MyDeviceGroup": {
        "selectionRule": "thingName: MyClientDevice*",
        "policyName": "MyRestrictivePolicy"
      }
    },
    "policies": {
      "MyRestrictivePolicy": {
        "AllowConnect": {
          "statementDescription": "Allow client devices to connect.",
          "operations": [
            "mqtt:connect"
          ],
          "resources": [
            "*"
          ]
        },
        "AllowPublish": {
          "statementDescription": "Allow client devices to publish on test/topic.",
          "operations": [
            "mqtt:publish"
          ],
          "resources": [
            "mqtt:topic:test/topic"
          ]
        },
        "AllowSubscribe": {
          "statementDescription": "Allow client devices to subscribe to test/topic/response.",
          "operations": [
            "mqtt:subscribe"
          ],
          "resources": [
            "mqtt:topicfilter:test/topic/response"
          ]
        }
      }
    }
  }
}
```

**Example: Configuration merge update (using a permissive policy)**  <a name="client-device-auth-component-configuration-example-permissive"></a>
The following example configuration specifies to allow all client devices to connect and publish/subscribe on all topics.  

```
{
  "deviceGroups": {
    "formatVersion": "2021-03-05",
    "definitions": {
      "MyPermissiveDeviceGroup": {
        "selectionRule": "thingName: *",
        "policyName": "MyPermissivePolicy"
      }
    },
    "policies": {
      "MyPermissivePolicy": {
        "AllowAll": {
          "statementDescription": "Allow client devices to perform all actions.",
          "operations": [
            "*"
          ],
          "resources": [
            "*"
          ]
        }
      }
    }
  }
}
```

------
#### [ v2.2.x ]

`deviceGroups`  <a name="client-device-auth-component-configuration-devicegroups"></a>
Device groups are groups of client devices that have permissions to connect and communicate with a core device. Use selection rules to identify groups of client devices, and define *client device authorization policies* that specify the permissions for each device group.  
This object contains the following information:    
`formatVersion`  
The format version for this configuration object.  
Choose from the following options:  
+ `2021-03-05`  
`definitions`  
The device groups for this core device. Each definition specifies a *selection rule* to evaluate if a client device is a member of the group. Each definition also specifies the permissions policy to apply to client devices that match the selection rule. If a client device is a member of multiple device groups, the device's permissions are comprised of each group's permissions policy.  
This object contains the following information:    
`groupNameKey`  
The name of this device group. Replace *groupNameKey* with a name that helps you identify this device group.  
This object contains the following information:    
`selectionRule`  
The query that specifies which client devices are members of this device group. When a client device connects, the core device evaluates this selection rule to determine if the client device is a member of this device group. If the client device is a member, the core device uses this device group's policy to authorize the client device's actions.  
Each selection rule comprises at least one *selection rule clause*, which is a single expression query that can match client devices. Selection rules use the same query syntax as AWS IoT fleet indexing. For more information about selection rule syntax, see [AWS IoT fleet indexing query syntax](https://docs.aws.amazon.com/iot/latest/developerguide/query-syntax.html) in the *AWS IoT Core Developer Guide*.  
Use the `*` wildcard to match multiple client devices with one selection rule clause. You can use this wildcard at the end of the thing name to match client devices whose names start with a string that you specify. You can also use this wildcard to match all client devices.  
To select a value that contains a colon character (`:`), escape the colon with a backslash character (`\\`). In formats such as JSON, you must escape backslash characters, so you enter two backslash characters before the colon character. For example, specify `thingName: MyTeam\\\\:ClientDevice1` to select a thing whose name is `MyTeam:ClientDevice1`.
You can specify the following selector:  
+ `thingName` – The name of a client device's AWS IoT thing.

**Example selection rule**  
The following selection rule matches client devices whose names are `MyClientDevice1` or `MyClientDevice2`.  

```
thingName: MyClientDevice1 OR thingName: MyClientDevice2
```

**Example selection rule (use wildcards)**  
The following selection rule matches client devices whose names start with `MyClientDevice`.  

```
thingName: MyClientDevice*
```

**Example selection rule (match all devices)**  
The following selection rule matches all client devices.  

```
thingName: *
```  
`policyName`  
The permissions policy that applies to client devices in this device group. Specify the name of a policy that you define in the `policies` object.  
`policies`  
The client device authorization policies for client devices that connect to the core device. Each authorization policy specifies a set of actions and the resources where a client device can perform those actions.  
This object contains the following information:    
`policyNameKey`  
The name of this authorization policy. Replace *policyNameKey* with a name that helps you identify this authorization policy. You use this policy name to define which policy applies to a device group.  
This object contains the following information:    
`statementNameKey`  
The name of this policy statement. Replace *statementNameKey* with a name that helps you identify this policy statement.  
This object contains the following information:    
`operations`  
The list of operations to allow for the resources in this policy.  
You can include any of the following operations:  
+ `mqtt:connect` – Grants permission to connect to the core device. Client devices must have this permission to connect to a core device.

  This operation supports the following resources:
  + `mqtt:clientId:deviceClientId` – Restrict access based on the client ID that a client device uses to connect to the core device's MQTT broker. Replace *deviceClientId* with the client ID to use.
+ `mqtt:publish` – Grants permission to publish MQTT messages to topics.

  This operation supports the following resources:
  + <a name="client-device-authorization-policy-resource-mqtt-topic"></a>`mqtt:topic:mqttTopic` – Restrict access based on the MQTT topic where a client device publishes a message. Replace *mqttTopic* with the topic to use.

    This resource doesn't support MQTT topic wildcards.
+ `mqtt:subscribe` – Grants permission to subscribe to MQTT topic filters to receive messages.

  This operation supports the following resources:
  + <a name="client-device-authorization-policy-resource-mqtt-topicfilter"></a>`mqtt:topicfilter:mqttTopicFilter` – Restrict access based on the MQTT topics where a client device can subscribe to messages. Replace *mqttTopicFilter* with the topic filter to use.

    This resource supports the `+` and `#` MQTT topic wildcards. For more information, see [MQTT topics](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html) in the *AWS IoT Core Developer Guide*.

    The client device can subscribe to the exact topic filters that you allow. For example, if you allow the client device to subscribe to the `mqtt:topicfilter:client/+/status` resource, the client device can subscribe to `client/+/status` but not `client/client1/status`.
You can specify the `*` wildcard to allow access to all actions.  
`resources`  
The list of resources to allow for the operations in this policy. Specify resources that correspond to the operations in this policy. For example, you might specify a list of MQTT topic resources (`mqtt:topic:mqttTopic`) in a policy that specifies the `mqtt:publish` operation.  
You can specify the `*` wildcard to allow access to all resources. You can't use the `*` wildcard to match partial resource identifiers. For example, you can specify **"resources": "\$1"**, but you can't specify **"resources": "mqtt:clientId:\$1"**.  
`statementDescription`  
(Optional) A description for this policy statement.

`certificates`  <a name="client-device-auth-component-configuration-certificates"></a>
(Optional) The certificate configuration options for this core device. This object contains the following information:    
`serverCertificateValiditySeconds`  
(Optional) The amount of time (in seconds) after which the local MQTT server certificate expires. You can configure this option to customize how often client devices disconnect and reconnect to the core device.  
This component rotates the local MQTT server certificate 24 hours before it expires. The MQTT broker, such as the [Moquette MQTT broker component](mqtt-broker-moquette-component.md), generates a new certificate and restarts. When this happens, all client devices connected to this core device are disconnected. Client devices can reconnect to the core device after a short period of time.  
Default: `604800` (7 days)  
Minimum value: `172800` (2 days)  
Maximum value: `864000` (10 days)

`performance`  
(Optional) The performance configuration options for this core device. This object contains the following information:    
`maxActiveAuthTokens`  
(Optional) The maximum number of active client device authorization tokens. You can increase this number to enable a greater number of client devices to connect to a single core device without reauthenticating them.  
Default: `2500`  
`cloudRequestQueueSize`  
(Optional) The maximum number of AWS Cloud requests to queue before this component rejects requests.  
Default: `100`  
`maxConcurrentCloudRequests`  
(Optional) The maximum number of concurrent requests to send to the AWS Cloud. You can increase this number to improve authentication performance on core devices where you connect large numbers of client devices.  
Default: `1`

**Example: Configuration merge update (using a restrictive policy)**  <a name="client-device-auth-component-configuration-example-restrictive"></a>
The following example configuration specifies to allow client devices whose names start with `MyClientDevice` to connect and publish/subscribe on all topics.  

```
{
  "deviceGroups": {
    "formatVersion": "2021-03-05",
    "definitions": {
      "MyDeviceGroup": {
        "selectionRule": "thingName: MyClientDevice*",
        "policyName": "MyRestrictivePolicy"
      }
    },
    "policies": {
      "MyRestrictivePolicy": {
        "AllowConnect": {
          "statementDescription": "Allow client devices to connect.",
          "operations": [
            "mqtt:connect"
          ],
          "resources": [
            "*"
          ]
        },
        "AllowPublish": {
          "statementDescription": "Allow client devices to publish on test/topic.",
          "operations": [
            "mqtt:publish"
          ],
          "resources": [
            "mqtt:topic:test/topic"
          ]
        },
        "AllowSubscribe": {
          "statementDescription": "Allow client devices to subscribe to test/topic/response.",
          "operations": [
            "mqtt:subscribe"
          ],
          "resources": [
            "mqtt:topicfilter:test/topic/response"
          ]
        }
      }
    }
  }
}
```

**Example: Configuration merge update (using a permissive policy)**  <a name="client-device-auth-component-configuration-example-permissive"></a>
The following example configuration specifies to allow all client devices to connect and publish/subscribe on all topics.  

```
{
  "deviceGroups": {
    "formatVersion": "2021-03-05",
    "definitions": {
      "MyPermissiveDeviceGroup": {
        "selectionRule": "thingName: *",
        "policyName": "MyPermissivePolicy"
      }
    },
    "policies": {
      "MyPermissivePolicy": {
        "AllowAll": {
          "statementDescription": "Allow client devices to perform all actions.",
          "operations": [
            "*"
          ],
          "resources": [
            "*"
          ]
        }
      }
    }
  }
}
```

------
#### [ v2.1.x ]

`deviceGroups`  <a name="client-device-auth-component-configuration-devicegroups"></a>
Device groups are groups of client devices that have permissions to connect and communicate with a core device. Use selection rules to identify groups of client devices, and define *client device authorization policies* that specify the permissions for each device group.  
This object contains the following information:    
`formatVersion`  
The format version for this configuration object.  
Choose from the following options:  
+ `2021-03-05`  
`definitions`  
The device groups for this core device. Each definition specifies a *selection rule* to evaluate if a client device is a member of the group. Each definition also specifies the permissions policy to apply to client devices that match the selection rule. If a client device is a member of multiple device groups, the device's permissions are comprised of each group's permissions policy.  
This object contains the following information:    
`groupNameKey`  
The name of this device group. Replace *groupNameKey* with a name that helps you identify this device group.  
This object contains the following information:    
`selectionRule`  
The query that specifies which client devices are members of this device group. When a client device connects, the core device evaluates this selection rule to determine if the client device is a member of this device group. If the client device is a member, the core device uses this device group's policy to authorize the client device's actions.  
Each selection rule comprises at least one *selection rule clause*, which is a single expression query that can match client devices. Selection rules use the same query syntax as AWS IoT fleet indexing. For more information about selection rule syntax, see [AWS IoT fleet indexing query syntax](https://docs.aws.amazon.com/iot/latest/developerguide/query-syntax.html) in the *AWS IoT Core Developer Guide*.  
Use the `*` wildcard to match multiple client devices with one selection rule clause. You can use this wildcard at the end of the thing name to match client devices whose names start with a string that you specify. You can also use this wildcard to match all client devices.  
To select a value that contains a colon character (`:`), escape the colon with a backslash character (`\\`). In formats such as JSON, you must escape backslash characters, so you enter two backslash characters before the colon character. For example, specify `thingName: MyTeam\\\\:ClientDevice1` to select a thing whose name is `MyTeam:ClientDevice1`.
You can specify the following selector:  
+ `thingName` – The name of a client device's AWS IoT thing.

**Example selection rule**  
The following selection rule matches client devices whose names are `MyClientDevice1` or `MyClientDevice2`.  

```
thingName: MyClientDevice1 OR thingName: MyClientDevice2
```

**Example selection rule (use wildcards)**  
The following selection rule matches client devices whose names start with `MyClientDevice`.  

```
thingName: MyClientDevice*
```

**Example selection rule (match all devices)**  
The following selection rule matches all client devices.  

```
thingName: *
```  
`policyName`  
The permissions policy that applies to client devices in this device group. Specify the name of a policy that you define in the `policies` object.  
`policies`  
The client device authorization policies for client devices that connect to the core device. Each authorization policy specifies a set of actions and the resources where a client device can perform those actions.  
This object contains the following information:    
`policyNameKey`  
The name of this authorization policy. Replace *policyNameKey* with a name that helps you identify this authorization policy. You use this policy name to define which policy applies to a device group.  
This object contains the following information:    
`statementNameKey`  
The name of this policy statement. Replace *statementNameKey* with a name that helps you identify this policy statement.  
This object contains the following information:    
`operations`  
The list of operations to allow for the resources in this policy.  
You can include any of the following operations:  
+ `mqtt:connect` – Grants permission to connect to the core device. Client devices must have this permission to connect to a core device.

  This operation supports the following resources:
  + `mqtt:clientId:deviceClientId` – Restrict access based on the client ID that a client device uses to connect to the core device's MQTT broker. Replace *deviceClientId* with the client ID to use.
+ `mqtt:publish` – Grants permission to publish MQTT messages to topics.

  This operation supports the following resources:
  + <a name="client-device-authorization-policy-resource-mqtt-topic"></a>`mqtt:topic:mqttTopic` – Restrict access based on the MQTT topic where a client device publishes a message. Replace *mqttTopic* with the topic to use.

    This resource doesn't support MQTT topic wildcards.
+ `mqtt:subscribe` – Grants permission to subscribe to MQTT topic filters to receive messages.

  This operation supports the following resources:
  + <a name="client-device-authorization-policy-resource-mqtt-topicfilter"></a>`mqtt:topicfilter:mqttTopicFilter` – Restrict access based on the MQTT topics where a client device can subscribe to messages. Replace *mqttTopicFilter* with the topic filter to use.

    This resource supports the `+` and `#` MQTT topic wildcards. For more information, see [MQTT topics](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html) in the *AWS IoT Core Developer Guide*.

    The client device can subscribe to the exact topic filters that you allow. For example, if you allow the client device to subscribe to the `mqtt:topicfilter:client/+/status` resource, the client device can subscribe to `client/+/status` but not `client/client1/status`.
You can specify the `*` wildcard to allow access to all actions.  
`resources`  
The list of resources to allow for the operations in this policy. Specify resources that correspond to the operations in this policy. For example, you might specify a list of MQTT topic resources (`mqtt:topic:mqttTopic`) in a policy that specifies the `mqtt:publish` operation.  
You can specify the `*` wildcard to allow access to all resources. You can't use the `*` wildcard to match partial resource identifiers. For example, you can specify **"resources": "\$1"**, but you can't specify **"resources": "mqtt:clientId:\$1"**.  
`statementDescription`  
(Optional) A description for this policy statement.

`certificates`  <a name="client-device-auth-component-configuration-certificates"></a>
(Optional) The certificate configuration options for this core device. This object contains the following information:    
`serverCertificateValiditySeconds`  
(Optional) The amount of time (in seconds) after which the local MQTT server certificate expires. You can configure this option to customize how often client devices disconnect and reconnect to the core device.  
This component rotates the local MQTT server certificate 24 hours before it expires. The MQTT broker, such as the [Moquette MQTT broker component](mqtt-broker-moquette-component.md), generates a new certificate and restarts. When this happens, all client devices connected to this core device are disconnected. Client devices can reconnect to the core device after a short period of time.  
Default: `604800` (7 days)  
Minimum value: `172800` (2 days)  
Maximum value: `864000` (10 days)

**Example: Configuration merge update (using a restrictive policy)**  <a name="client-device-auth-component-configuration-example-restrictive"></a>
The following example configuration specifies to allow client devices whose names start with `MyClientDevice` to connect and publish/subscribe on all topics.  

```
{
  "deviceGroups": {
    "formatVersion": "2021-03-05",
    "definitions": {
      "MyDeviceGroup": {
        "selectionRule": "thingName: MyClientDevice*",
        "policyName": "MyRestrictivePolicy"
      }
    },
    "policies": {
      "MyRestrictivePolicy": {
        "AllowConnect": {
          "statementDescription": "Allow client devices to connect.",
          "operations": [
            "mqtt:connect"
          ],
          "resources": [
            "*"
          ]
        },
        "AllowPublish": {
          "statementDescription": "Allow client devices to publish on test/topic.",
          "operations": [
            "mqtt:publish"
          ],
          "resources": [
            "mqtt:topic:test/topic"
          ]
        },
        "AllowSubscribe": {
          "statementDescription": "Allow client devices to subscribe to test/topic/response.",
          "operations": [
            "mqtt:subscribe"
          ],
          "resources": [
            "mqtt:topicfilter:test/topic/response"
          ]
        }
      }
    }
  }
}
```

**Example: Configuration merge update (using a permissive policy)**  <a name="client-device-auth-component-configuration-example-permissive"></a>
The following example configuration specifies to allow all client devices to connect and publish/subscribe on all topics.  

```
{
  "deviceGroups": {
    "formatVersion": "2021-03-05",
    "definitions": {
      "MyPermissiveDeviceGroup": {
        "selectionRule": "thingName: *",
        "policyName": "MyPermissivePolicy"
      }
    },
    "policies": {
      "MyPermissivePolicy": {
        "AllowAll": {
          "statementDescription": "Allow client devices to perform all actions.",
          "operations": [
            "*"
          ],
          "resources": [
            "*"
          ]
        }
      }
    }
  }
}
```

------
#### [ v2.0.x ]

`deviceGroups`  <a name="client-device-auth-component-configuration-devicegroups"></a>
Device groups are groups of client devices that have permissions to connect and communicate with a core device. Use selection rules to identify groups of client devices, and define *client device authorization policies* that specify the permissions for each device group.  
This object contains the following information:    
`formatVersion`  
The format version for this configuration object.  
Choose from the following options:  
+ `2021-03-05`  
`definitions`  
The device groups for this core device. Each definition specifies a *selection rule* to evaluate if a client device is a member of the group. Each definition also specifies the permissions policy to apply to client devices that match the selection rule. If a client device is a member of multiple device groups, the device's permissions are comprised of each group's permissions policy.  
This object contains the following information:    
`groupNameKey`  
The name of this device group. Replace *groupNameKey* with a name that helps you identify this device group.  
This object contains the following information:    
`selectionRule`  
The query that specifies which client devices are members of this device group. When a client device connects, the core device evaluates this selection rule to determine if the client device is a member of this device group. If the client device is a member, the core device uses this device group's policy to authorize the client device's actions.  
Each selection rule comprises at least one *selection rule clause*, which is a single expression query that can match client devices. Selection rules use the same query syntax as AWS IoT fleet indexing. For more information about selection rule syntax, see [AWS IoT fleet indexing query syntax](https://docs.aws.amazon.com/iot/latest/developerguide/query-syntax.html) in the *AWS IoT Core Developer Guide*.  
Use the `*` wildcard to match multiple client devices with one selection rule clause. You can use this wildcard at the end of the thing name to match client devices whose names start with a string that you specify. You can also use this wildcard to match all client devices.  
To select a value that contains a colon character (`:`), escape the colon with a backslash character (`\\`). In formats such as JSON, you must escape backslash characters, so you enter two backslash characters before the colon character. For example, specify `thingName: MyTeam\\\\:ClientDevice1` to select a thing whose name is `MyTeam:ClientDevice1`.
You can specify the following selector:  
+ `thingName` – The name of a client device's AWS IoT thing.

**Example selection rule**  
The following selection rule matches client devices whose names are `MyClientDevice1` or `MyClientDevice2`.  

```
thingName: MyClientDevice1 OR thingName: MyClientDevice2
```

**Example selection rule (use wildcards)**  
The following selection rule matches client devices whose names start with `MyClientDevice`.  

```
thingName: MyClientDevice*
```

**Example selection rule (match all devices)**  
The following selection rule matches all client devices.  

```
thingName: *
```  
`policyName`  
The permissions policy that applies to client devices in this device group. Specify the name of a policy that you define in the `policies` object.  
`policies`  
The client device authorization policies for client devices that connect to the core device. Each authorization policy specifies a set of actions and the resources where a client device can perform those actions.  
This object contains the following information:    
`policyNameKey`  
The name of this authorization policy. Replace *policyNameKey* with a name that helps you identify this authorization policy. You use this policy name to define which policy applies to a device group.  
This object contains the following information:    
`statementNameKey`  
The name of this policy statement. Replace *statementNameKey* with a name that helps you identify this policy statement.  
This object contains the following information:    
`operations`  
The list of operations to allow for the resources in this policy.  
You can include any of the following operations:  
+ `mqtt:connect` – Grants permission to connect to the core device. Client devices must have this permission to connect to a core device.

  This operation supports the following resources:
  + `mqtt:clientId:deviceClientId` – Restrict access based on the client ID that a client device uses to connect to the core device's MQTT broker. Replace *deviceClientId* with the client ID to use.
+ `mqtt:publish` – Grants permission to publish MQTT messages to topics.

  This operation supports the following resources:
  + <a name="client-device-authorization-policy-resource-mqtt-topic"></a>`mqtt:topic:mqttTopic` – Restrict access based on the MQTT topic where a client device publishes a message. Replace *mqttTopic* with the topic to use.

    This resource doesn't support MQTT topic wildcards.
+ `mqtt:subscribe` – Grants permission to subscribe to MQTT topic filters to receive messages.

  This operation supports the following resources:
  + <a name="client-device-authorization-policy-resource-mqtt-topicfilter"></a>`mqtt:topicfilter:mqttTopicFilter` – Restrict access based on the MQTT topics where a client device can subscribe to messages. Replace *mqttTopicFilter* with the topic filter to use.

    This resource supports the `+` and `#` MQTT topic wildcards. For more information, see [MQTT topics](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html) in the *AWS IoT Core Developer Guide*.

    The client device can subscribe to the exact topic filters that you allow. For example, if you allow the client device to subscribe to the `mqtt:topicfilter:client/+/status` resource, the client device can subscribe to `client/+/status` but not `client/client1/status`.
You can specify the `*` wildcard to allow access to all actions.  
`resources`  
The list of resources to allow for the operations in this policy. Specify resources that correspond to the operations in this policy. For example, you might specify a list of MQTT topic resources (`mqtt:topic:mqttTopic`) in a policy that specifies the `mqtt:publish` operation.  
You can specify the `*` wildcard to allow access to all resources. You can't use the `*` wildcard to match partial resource identifiers. For example, you can specify **"resources": "\$1"**, but you can't specify **"resources": "mqtt:clientId:\$1"**.  
`statementDescription`  
(Optional) A description for this policy statement.

**Example: Configuration merge update (using a restrictive policy)**  <a name="client-device-auth-component-configuration-example-restrictive"></a>
The following example configuration specifies to allow client devices whose names start with `MyClientDevice` to connect and publish/subscribe on all topics.  

```
{
  "deviceGroups": {
    "formatVersion": "2021-03-05",
    "definitions": {
      "MyDeviceGroup": {
        "selectionRule": "thingName: MyClientDevice*",
        "policyName": "MyRestrictivePolicy"
      }
    },
    "policies": {
      "MyRestrictivePolicy": {
        "AllowConnect": {
          "statementDescription": "Allow client devices to connect.",
          "operations": [
            "mqtt:connect"
          ],
          "resources": [
            "*"
          ]
        },
        "AllowPublish": {
          "statementDescription": "Allow client devices to publish on test/topic.",
          "operations": [
            "mqtt:publish"
          ],
          "resources": [
            "mqtt:topic:test/topic"
          ]
        },
        "AllowSubscribe": {
          "statementDescription": "Allow client devices to subscribe to test/topic/response.",
          "operations": [
            "mqtt:subscribe"
          ],
          "resources": [
            "mqtt:topicfilter:test/topic/response"
          ]
        }
      }
    }
  }
}
```

**Example: Configuration merge update (using a permissive policy)**  <a name="client-device-auth-component-configuration-example-permissive"></a>
The following example configuration specifies to allow all client devices to connect and publish/subscribe on all topics.  

```
{
  "deviceGroups": {
    "formatVersion": "2021-03-05",
    "definitions": {
      "MyPermissiveDeviceGroup": {
        "selectionRule": "thingName: *",
        "policyName": "MyPermissivePolicy"
      }
    },
    "policies": {
      "MyPermissivePolicy": {
        "AllowAll": {
          "statementDescription": "Allow client devices to perform all actions.",
          "operations": [
            "*"
          ],
          "resources": [
            "*"
          ]
        }
      }
    }
  }
}
```

------

## Local log file


This component uses the same log file as the [Greengrass nucleus](greengrass-nucleus-component.md) component.

------
#### [ Linux ]

```
/greengrass/v2/logs/greengrass.log
```

------
#### [ Windows ]

```
C:\greengrass\v2\logs\greengrass.log
```

------

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the path to the AWS IoT Greengrass root folder.

------
#### [ Linux ]

  ```
  sudo tail -f /greengrass/v2/logs/greengrass.log
  ```

------
#### [ Windows (PowerShell) ]

  ```
  Get-Content C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
  ```

------

## Changelog


The following table describes the changes in each version of the component.


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.5.5  |  Version updated for Greengrass nucleus version 2.16.0 release.  | 
|  2.5.4  | Version updated for Greengrass nucleus version 2.15.0 release. | 
|  2.5.3  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/client-device-auth-component.html)  | 
|  2.5.2  |  Version updated for Greengrass nucleus version 2.14.0 release.  | 
|  2.5.1  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/client-device-auth-component.html)  | 
|  2.5.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/client-device-auth-component.html)  | 
|  2.4.5  | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/client-device-auth-component.html) | 
|  2.4.4  | Version updated for Greengrass nucleus version 2.12.0 release. | 
|  2.4.3  | Version updated for Greengrass nucleus version 2.11.0 release. | 
|  2.4.2  |  <a name="changelog-client-device-auth-2.4.2"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/client-device-auth-component.html)  | 
|  2.4.1  | Version updated for Greengrass nucleus version 2.10.0 release. | 
|  2.4.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/client-device-auth-component.html)  | 
|  2.3.2  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/client-device-auth-component.html)  | 
|  2.3.1  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/client-device-auth-component.html)  | 
|  2.3.0  |   This version is no longer available. The improvements in this version are available in later versions of this component.  New features [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/client-device-auth-component.html)  | 
|  2.2.3  | Version updated for Greengrass nucleus version 2.8.0 release. | 
|  2.2.2  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/client-device-auth-component.html)  | 
|  2.2.1  |  Version updated for Greengrass nucleus version 2.7.0 release.  | 
|  2.2.0  |  <a name="changelog-client-device-auth-2.2.0"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/client-device-auth-component.html)  | 
|  2.1.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/client-device-auth-component.html)  | 
|  2.0.4  |  Version updated for Greengrass nucleus version 2.5.0 release.  | 
|  2.0.3  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/client-device-auth-component.html)  | 
|  2.0.2  |  Version updated for Greengrass nucleus version 2.4.0 release.  | 
|  2.0.1  |  Version updated for Greengrass nucleus version 2.3.0 release.  | 
|  2.0.0  |  Initial version.  | 

# CloudWatch metrics


The Amazon CloudWatch metrics component (`aws.greengrass.Cloudwatch`) publishes custom metrics from Greengrass core devices to Amazon CloudWatch. The component enables components to publish CloudWatch metrics, which you can use to monitor and analyze the Greengrass core device's environment. For more information, see [Using Amazon CloudWatch metrics](https://docs.aws.amazon.com//AmazonCloudWatch/latest/monitoring/working_with_metrics.html) in the *Amazon CloudWatch User Guide*.

To publish a CloudWatch metric with this component, publish a message to a topic where this component subscribes. By default, this component subscribes to the `cloudwatch/metric/put` [local publish/subscribe](ipc-publish-subscribe.md) topic. You can specify other topics, including AWS IoT Core MQTT topics, when you deploy this component.

This component batches metrics that are in the same namespace and publishes them to CloudWatch at regular intervals.

**Note**  
This component provides similar functionality to the CloudWatch metrics connector in AWS IoT Greengrass V1. For more information, see [CloudWatch metrics connector](https://docs.aws.amazon.com/greengrass/latest/developerguide/cloudwatch-metrics-connector.html) in the *AWS IoT Greengrass V1 Developer Guide*.

**Topics**
+ [

## Versions
](#cloudwatch-metrics-component-versions)
+ [

## Type
](#cloudwatch-metrics-component-type)
+ [

## Operating system
](#cloudwatch-metrics-component-os-support)
+ [

## Requirements
](#cloudwatch-metrics-component-requirements)
+ [

## Dependencies
](#cloudwatch-metrics-component-dependencies)
+ [

## Configuration
](#cloudwatch-metrics-component-configuration)
+ [

## Input data
](#cloudwatch-metrics-component-input-data)
+ [

## Output data
](#cloudwatch-metrics-component-output-data)
+ [

## Licenses
](#cloudwatch-metrics-component-licenses)
+ [

## Local log file
](#cloudwatch-metrics-component-log-file)
+ [

## Changelog
](#cloudwatch-metrics-component-changelog)
+ [

## See also
](#cloudwatch-metrics-component-see-also)

## Versions


This component has the following versions:
+ 3.2.x
+ 3.1.x
+ 3.0.x
+ 2.1.x
+ 2.0.x

For information about changes in each version of the component, see the [changelog](#cloudwatch-metrics-component-changelog).

## Type


------
#### [ v3.x ]

<a name="public-component-type-generic"></a>This <a name="public-component-type-generic-phrase"></a>component is a generic component (`aws.greengrass.generic`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs the component's lifecycle scripts.

------
#### [ v2.x ]

<a name="public-component-type-lambda"></a>This <a name="public-component-type-lambda-phrase"></a>component is a Lambda component (`aws.greengrass.lambda`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs this component's Lambda function using the [Lambda launcher component](lambda-launcher-component.md).

------

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


------
#### [ v3.x ]

This component can be installed on core devices that run the following operating systems:
+ Linux
+ Windows

------
#### [ v2.x ]

This component can be installed on Linux core devices only.

------

## Requirements


This component has the following requirements:

------
#### [ 3.x ]
+ <a name="public-component-python3-requirement"></a>[Python](https://www.python.org/) version 3.7 installed on the core device and added to the PATH environment variable.
+ The [Greengrass device role](device-service-role.md) must allow the `cloudwatch:PutMetricData` action, as shown in the following example IAM policy.

------
#### [ JSON ]

****  

  ```
  {
    "Version":"2012-10-17",		 	 	 
    "Statement": [
      {
        "Action": [
          "cloudwatch:PutMetricData"
        ],
        "Effect": "Allow",
        "Resource": "*"
      }
    ]
  }
  ```

------

  For more information, see [Amazon CloudWatch permissions reference](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/permissions-reference-cw.html) in the *Amazon CloudWatch User Guide*.

------
#### [ 2.x ]
+ <a name="core-device-lambda-function-requirements"></a>Your core device must meet the requirements to run Lambda functions. If you want the core device to run containerized Lambda functions, the device must meet the requirements to do so. For more information, see [Lambda function requirements](setting-up.md#greengrass-v2-lambda-requirements).
+ <a name="public-component-python3-requirement"></a>[Python](https://www.python.org/) version 3.7 installed on the core device and added to the PATH environment variable.
+ The [Greengrass device role](device-service-role.md) must allow the `cloudwatch:PutMetricData` action, as shown in the following example IAM policy.

------
#### [ JSON ]

****  

  ```
  {
    "Version":"2012-10-17",		 	 	 
    "Statement": [
      {
        "Action": [
          "cloudwatch:PutMetricData"
        ],
        "Effect": "Allow",
        "Resource": "*"
      }
    ]
  }
  ```

------

  For more information, see [Amazon CloudWatch permissions reference](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/permissions-reference-cw.html) in the *Amazon CloudWatch User Guide*.
+ <a name="connector-component-legacy-subscription-router-dependency"></a>To receive output data from this component, you must merge the following configuration update for the [legacy subscription router component](legacy-subscription-router-component.md) (`aws.greengrass.LegacySubscriptionRouter`) when you deploy this component. This configuration specifies the topic where this component publishes responses.

------
#### [ Legacy subscription router v2.1.x ]

  ```
  {
    "subscriptions": {
      "aws-greengrass-cloudwatch": {
        "id": "aws-greengrass-cloudwatch",
        "source": "component:aws.greengrass.Cloudwatch",
        "subject": "cloudwatch/metric/put/status",
        "target": "cloud"
      }
    }
  }
  ```

------
#### [ Legacy subscription router v2.0.x ]

  ```
  {
    "subscriptions": {
      "aws-greengrass-cloudwatch": {
        "id": "aws-greengrass-cloudwatch",
        "source": "arn:aws:lambda:region:aws:function:aws-greengrass-cloudwatch:version",
        "subject": "cloudwatch/metric/put/status",
        "target": "cloud"
      }
    }
  }
  ```<a name="connector-component-legacy-subscription-router-dependency-replace"></a>
  + Replace *region* with the AWS Region that you use.
  + Replace *version* with the version of the Lambda function that this component runs. To find the Lambda function version, you must view the recipe for the version of this component that you want to deploy. Open this component's details page in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass), and look for the **Lambda function** key-value pair. This key-value pair contains the name and version of the Lambda function.

**Important**  <a name="connector-component-legacy-subscription-router-dependency-note"></a>
You must update the Lambda function version on the legacy subscription router every time you deploy this component. This ensures that you use the correct Lambda function version for the component version that you deploy.

------

  <a name="connector-component-create-deployments"></a>For more information, see [Create deployments](create-deployments.md).

------

### Endpoints and ports


This component must be able to perform outbound requests to the following endpoints and ports, in addition to endpoints and ports required for basic operation. For more information, see [Allow device traffic through a proxy or firewall](allow-device-traffic.md).


| Endpoint | Port | Required | Description | 
| --- | --- | --- | --- | 
|  `monitoring.region.amazonaws.com`  | 443 | Yes |  Upload CloudWatch metrics.  | 

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#cloudwatch-metrics-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

------
#### [ 3.2.0 ]

The following table lists the dependencies for versions 3.2.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <3.0.0 | Soft | 
| [Token exchange service](token-exchange-service-component.md) | >=0.0.0 | Hard | 

------
#### [ 3.0.0 - 3.1.0 ]

The following table lists the dependencies for versions 3.0.0 to 3.1.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <3.0.0 | Soft | 
| [Token exchange service](token-exchange-service-component.md) | >=0.0.0 | Hard | 

------
#### [ 2.1.4 - 2.1.9 ]

The following table lists the dependencies for versions 2.1.4 to 2.1.9 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <3.0.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.1.4 - 2.1.8 ]

The following table lists the dependencies for version 2.1.4 and 2.1.8 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <3.0.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.1.2 - 2.1.3 ]

The following table lists the dependencies for version 2.1.2 and 2.1.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.8.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.1.1 ]

The following table lists the dependencies for version 2.1.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.7.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.0.8 - 2.1.0 ]

The following table lists the dependencies for versions 2.0.8 to 2.1.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.6.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.0.7 ]

The following table lists the dependencies for version 2.0.7 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.5.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.0.6 ]

The following table lists the dependencies for version 2.0.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.4.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.0.5 ]

The following table lists the dependencies for version 2.0.5 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.3.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.0.4 ]

The following table lists the dependencies for version 2.0.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.2.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.0.3 ]

The following table lists the dependencies for version 2.0.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.3 <2.1.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | >=1.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | >=1.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | >=1.0.0  | Hard | 

------

For more information about component dependencies, see the [component recipe reference](component-recipe-reference.md#recipe-reference-component-dependencies).

## Configuration


This component provides the following configuration parameters that you can customize when you deploy the component.

------
#### [ v3.x ]

 `PublishInterval`   
(Optional) The maximum number of seconds to wait before the component publishes batched metrics for a given namespace. To configure the component to publish metrics as it receives them, which means without batching, specify `0`.  
The component publishes to CloudWatch after it receives 20 metrics in the same namespace or after the interval that you specify.  
The component doesn't specify the order in which events publish.
This value can be a maximum of 900 seconds.  
Default: 10 seconds

 `MaxMetricsToRetain`   
(Optional) The maximum number of metrics across all namespaces to save in memory before the component replaces them with newer metrics.  
This limit applies when the core device doesn't have a connection to the internet, so the component buffers the metrics to publish later. When the buffer is full, the component replaces the oldest metrics with newer ones. Metrics in a given namespace replace only metrics in the same namespace.  
If the host process for the component is interrupted, the component doesn't save metrics. This can happen during a deployment or when the core device restarts, for example.
This value must be at least 2,000 metrics.  
Default: 5,000 metrics

`InputTopic`  
(Optional) The topic to which the component subscribes to receive messages. If you specify `true` for `PubSubToIoTCore`, you can use MQTT wildcards (\$1 and \$1) in this topic.  
Default: `cloudwatch/metric/put`

`OutputTopic`  
(Optional) The topic to which the component publishes status responses.  
Default: `cloudwatch/metric/put/status`

`PubSubToIoTCore`  
(Optional) String value that defines whether to publish and subscribe to AWS IoT Core MQTT topics. Supported values are `true` and `false`.  
Default: `false`

`LogLevel`  
(Optional) The logging level for the component. Choose from the following log levels, listed here in level order:  
+ `DEBUG`
+ `INFO`
+ `WARNING`
+ `ERROR`
+ `CRITICAL`
Default: `INFO`

`UseInstaller`  
(Optional) Boolean value that defines whether to use the installer script in this component to install this component's SDK dependencies.  
Set this value to `false` if you want to use a custom script to install dependencies, or if you want to include runtime dependencies in a pre-built Linux image. To use this component, you must install the following libraries, including any dependencies, and make them available to the default Greengrass system user.  
+ [AWS IoT Device SDK v2 for Python](https://github.com/aws/aws-iot-device-sdk-python-v2)
+ [AWS SDK for Python (Boto3)](http://boto.readthedocs.org/en/latest/ref/)
Default: `true`

`PublishRegion`  
(Optional) The AWS Region to which to publish CloudWatch metrics. This value overrides the default Region for the core device. This parameter is required only for cross-Region metrics.

`accessControl`  
(Optional) The object that contains the [authorization policy](interprocess-communication.md#ipc-authorization-policies) that allows the component to publish and subscribe to the specified topics. If you specify custom values for `InputTopic` and `OutputTopic`, you must update the resource values in this object.   
Default:   

```
{
  "aws.greengrass.ipc.pubsub": {
    "aws.greengrass.Cloudwatch:pubsub:1": {
      "policyDescription": "Allows access to subscribe to input topics.",
      "operations": [
        "aws.greengrass#SubscribeToTopic"
      ],
      "resources": [
        "cloudwatch/metric/put"
      ]
    },
    "aws.greengrass.Cloudwatch:pubsub:2": {
      "policyDescription": "Allows access to publish to output topics.",
      "operations": [
        "aws.greengrass#PublishToTopic"
      ],
      "resources": [
        "cloudwatch/metric/put/status"
      ]
    }
  },
  "aws.greengrass.ipc.mqttproxy": {
    "aws.greengrass.Cloudwatch:mqttproxy:1": {
      "policyDescription": "Allows access to subscribe to input topics.",
      "operations": [
        "aws.greengrass#SubscribeToIoTCore"
      ],
      "resources": [
        "cloudwatch/metric/put"
      ]
    },
    "aws.greengrass.Cloudwatch:mqttproxy:2": {
      "policyDescription": "Allows access to publish to output topics.",
      "operations": [
        "aws.greengrass#PublishToIoTCore"
      ],
      "resources": [
        "cloudwatch/metric/put/status"
      ]
    }
  }
}
```

**Example: Configuration merge update**  

```
{
  "PublishInterval": 0,
  "PubSubToIoTCore": true
}
```

------
#### [ v2.x ]

**Note**  <a name="connector-component-lambda-parameters"></a>
This component's default configuration includes Lambda function parameters. We recommend that you edit only the following parameters to configure this component on your devices.

 `lambdaParams`   
An object that contains the parameters for this component's Lambda function. This object contains the following information:    
 `EnvironmentVariables`   
An object that contains the Lambda function's parameters. This object contains the following information:    
 `PUBLISH_INTERVAL`   
(Optional) The maximum number of seconds to wait before the component publishes batched metrics for a given namespace. To configure the component to publish metrics as it receives them, which means without batching, specify `0`.  
The component publishes to CloudWatch after it receives 20 metrics in the same namespace or after the interval that you specify.  
The component doesn't guarantee the order in which events publish.
This value can be at most 900 seconds.  
Default: 10 seconds  
 `MAX_METRICS_TO_RETAIN`   
(Optional) The maximum number of metrics across all namespaces to save in memory before the component replaces them with newer metrics.  
This limit applies when the core device doesn't have a connection to the internet, so the component buffers the metrics to publish later. When the buffer is full, the component replaces the oldest metrics with newer ones. Metrics in a given namespace replace only metrics in the same namespace.  
If the host process for the component is interrupted, the component doesn't save metrics. This can happen during a deployment or when the core device restarts, for example.
This value must be at least 2,000 metrics.  
Default: 5,000 metrics  
 `PUBLISH_REGION`   
(Optional) The AWS Region to which to publish CloudWatch metrics. This value overrides the default Region for the core device. This parameter is required only for cross-Region metrics.

`containerMode`  <a name="connector-component-container-mode-parameter"></a>
(Optional) The containerization mode for this component. Choose from the following options:  <a name="lambda-function-component-container-mode-parameter"></a>
+ `NoContainer` – The component doesn't run in an isolated runtime environment.
+ `GreengrassContainer` – The component runs in an isolated runtime environment inside the AWS IoT Greengrass container.
Default: `GreengrassContainer`

 `containerParams`   
<a name="connector-component-container-params-description"></a>(Optional) An object that contains the container parameters for this component. The component uses these parameters if you specify `GreengrassContainer` for `containerMode`.  
This object contains the following information:    
 `memorySize`   
<a name="connector-component-container-params-memory-size-description"></a>(Optional) The amount of memory (in kilobytes) to allocate to the component.  
Defaults to 64 MB (65,535 KB).

`pubsubTopics`  <a name="connector-component-pubsub-topics-parameter"></a>
(Optional) An object that contains the topics where the component subscribes to receive messages. You can specify each topic and whether the component subscribes to MQTT topics from AWS IoT Core or local publish/subscribe topics.  
This object contains the following information:    
`0` – This is an array index as a string.  
An object that contains the following information:    
`type`  
(Optional) The type of publish/subscribe messaging that this component uses to subscribe to messages. Choose from the following options:  
+ `PUB_SUB` – Subscribe to local publish/subscribe messages. If you choose this option, the topic can't contain MQTT wildcards. For more information about how to send messages from custom component when you specify this option, see [Publish/subscribe local messages](ipc-publish-subscribe.md).
+ `IOT_CORE` – Subscribe to AWS IoT Core MQTT messages. If you choose this option, the topic can contain MQTT wildcards. For more information about how to send messages from custom components when you specify this option, see [Publish/subscribe AWS IoT Core MQTT messages](ipc-iot-core-mqtt.md).
Default: `PUB_SUB`  
`topic`  
(Optional) The topic to which the component subscribes to receive messages. If you specify `IotCore` for `type`, you can use MQTT wildcards (`+` and `#`) in this topic.

**Example: Configuration merge update (container mode)**  

```
{
  "containerMode": "GreengrassContainer"
}
```

**Example: Configuration merge update (no container mode)**  

```
{
  "containerMode": "NoContainer"
}
```

------

## Input data


This component accepts metrics on the following topic and publishes the metrics to CloudWatch. <a name="connector-component-local-publish"></a>By default, this component subscribes to local publish/subscribe messages. For more information about how to publish messages to this component from your custom components, see [Publish/subscribe local messages](ipc-publish-subscribe.md). 

Beginning with component version v3.0.0, you can optionally configure this component to subscribe to an MQTT topic by setting the `PubSubToIoTCore` configuration parameter to `true`. For more information about publishing messages to an MQTT topic in your custom components, see [Publish/subscribe AWS IoT Core MQTT messages](ipc-iot-core-mqtt.md).

 **Default topic:** `cloudwatch/metric/put` 

<a name="connector-component-input-properties"></a>The message accepts the following properties. Input messages must be in JSON format.

 `request`   
The metric in this message.  
The request object contains the metric data to publish to CloudWatch. The metric values must meet the specifications of the [https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_PutMetricData.html](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_PutMetricData.html) operation.  
Type: `object` that contains the following information:    
 `namespace`   
The user-defined namespace for the metric data in this request. CloudWatch uses namespaces as containers for metric data points.  
You can't specify a namespace that begins with the reserved string `AWS/`.
Type: `string`  
Valid pattern: `[^:].*`  
 `metricData`   
The data for the metric.  
Type: `object` that contains the following information:    
 `metricName`   
The name of the metric.  
Type: `string`  
 `value`   
The value for the metric.  
CloudWatch rejects values that are too small or too large. The value must be between `8.515920e-109` and `1.174271e+108` (Base 10) or `2e-360` and `2e360` (Base 2). CloudWatch doesn't support special values such as `NaN`, `+Infinity`, and `-Infinity`.
Type: `double`  
 `dimensions`   
(Optional) The dimensions for the metric. Dimensions provide additional information about the metric and its data. A metric can define up to 10 dimensions.  
This component automatically includes a dimension named `coreName`, where the value is the name of the core device.  
Type: `array` of objects that each contain the following information:    
 `name`   
(Optional) The dimension name.  
Type: `string`  
 `value`   
(Optional) The dimension value.  
Type: `string`  
 `timestamp`   
(Optional) The time at which the metric data was received, expressed in seconds in Unix epoch time.  
Defaults to the time at which the component receives the message.  
Type: `double`  
If you use between versions 2.0.3 and 2.0.7 of this component, we recommend that you retrieve the timestamp separately for each metric when you send multiple metrics from a single source. Don't use a variable to store the timestamp.  
 `unit`   
(Optional) The unit of the metric.  
Type: `string`  
Valid values: `Seconds`, `Microseconds`, `Milliseconds`, `Bytes`, `Kilobytes`, `Megabytes`, `Gigabytes`, `Terabytes`, `Bits`, `Kilobits`, `Megabits`, `Gigabits`, `Terabits`, `Percent`, `Count`, `Bytes/Second`, `Kilobytes/Second`, `Megabytes/Second`, `Gigabytes/Second`, `Terabytes/Second`, `Bits/Second`, `Kilobits/Second`, `Megabits/Second`, `Gigabits/Second`, `Terabits/Second`, `Count/Second`, `None`  
Defaults to `None`.

**Note**  
All quotas that apply to the CloudWatch `PutMetricData` API apply to metrics that you publish with this component. The following quotas are especially important:  
40 KB limit on the API payload
20 metrics per API request
150 transactions per second (TPS) for the `PutMetricData` API
For more information, see [CloudWatch service quotas](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_limits.html) in the *CloudWatch User Guide*.

**Example input**  

```
{
  "request": {
    "namespace": "Greengrass",
    "metricData": {
      "metricName": "latency",
      "dimensions": [
        {
          "name": "hostname",
          "value": "test_hostname"
        }
      ],
      "timestamp": 1539027324,
      "value": 123.0,
      "unit": "Seconds"
    }
  }
}
```

## Output data


 <a name="connector-component-output-data-pubsub"></a>This component publishes responses as output data on the following local publish/subscribe topic by default. For more information about how to subscribe to messages on this topic in your custom components, see [Publish/subscribe local messages](ipc-publish-subscribe.md). 

You can optionally configure this component to publish to an MQTT topic by setting the `PubSubToIoTCore` configuration parameter to `true`. For more information about subscribing to messages on an MQTT topic in your custom components, see [Publish/subscribe AWS IoT Core MQTT messages](ipc-iot-core-mqtt.md).

**Note**  
Component versions 2.0.x publish responses as output data on an MQTT topic by default. You must specify the topic as the `subject` in the configuration for the [legacy subscription router component](legacy-subscription-router-component.md).

 **Default topic:** `cloudwatch/metric/put/status` 

**Example output: Success**  
The response includes the namespace of the metric data and the `RequestId` field from the CloudWatch response.  

```
{
  "response": {
    "cloudwatch_rid": "70573243-d723-11e8-b095-75ff2EXAMPLE",
    "namespace": "Greengrass",
    "status": "success"
  }
}
```

**Example output: Failure**  

```
{
  "response" : {
    "namespace": "Greengrass",
    "error": "InvalidInputException",
    "error_message": "cw metric is invalid",
    "status": "fail"
  }
}
```

**Note**  <a name="connector-component-retryable-error"></a>
If the component detects an error that can be retried, such as a connection error, it retries the publish in the next batch.

## Licenses


This component includes the following third-party software/licensing:<a name="boto-3-licenses"></a>
+ [AWS SDK for Python (Boto3)](https://pypi.org/project/boto3/)/Apache License 2.0
+ [botocore](https://pypi.org/project/botocore/)/Apache License 2.0
+ [dateutil](https://pypi.org/project/python-dateutil/1.4/)/PSF License
+ [docutils](https://pypi.org/project/docutils/)/BSD License, GNU General Public License (GPL), Python Software Foundation License, Public Domain
+ [jmespath](https://pypi.org/project/jmespath/)/MIT License
+ [s3transfer](https://pypi.org/project/s3transfer/)/Apache License 2.0
+ [urllib3](https://pypi.org/project/urllib3/)/MIT License

<a name="component-core-software-license"></a>This component is released under the [Greengrass Core Software License Agreement](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf).

## Local log file


This component uses the following log file.

------
#### [ Linux ]

```
/greengrass/v2/logs/aws.greengrass.Cloudwatch.log
```

------
#### [ Windows ]

```
C:\greengrass\v2\logs\aws.greengrass.Cloudwatch.log
```

------

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the path to the AWS IoT Greengrass root folder.

------
#### [ Linux ]

  ```
  sudo tail -f /greengrass/v2/logs/aws.greengrass.Cloudwatch.log
  ```

------
#### [ Windows (PowerShell) ]

  ```
  Get-Content C:\greengrass\v2\logs\aws.greengrass.Cloudwatch.log -Tail 10 -Wait
  ```

------

## Changelog


The following table describes the changes in each version of the component.

------
#### [ v3.x ]


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  3.2.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/cloudwatch-metrics-component.html)  | 
|  3.1.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/cloudwatch-metrics-component.html)  | 
|  3.0.0  |  <a name="changelog-cloudwatch-metrics-3.0.0-major-version-changes"></a>This version of the CloudWatch metrics component expects different configuration parameters than version 2.x. If you use a non-default configuration for version 2.x, and you want to upgrade from v2.x to v3.x, you must update the component's configuration. For more information, see [CloudWatch metrics component configuration](#cloudwatch-metrics-component-configuration). <a name="changelog-cloudwatch-metrics-3.0.0"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/cloudwatch-metrics-component.html)  | 

------
#### [ v2.x ]


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.1.8  |  Version updated for Greengrass nucleus version 2.13.0 release.  | 
|  2.1.3  |  Version updated for Greengrass nucleus version 2.11.0 release.  | 
|  2.1.2  |  Version updated for Greengrass nucleus version 2.7.0 release.  | 
|  2.1.1  |  Version updated for Greengrass nucleus version 2.6.0 release.  | 
|  2.1.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/cloudwatch-metrics-component.html)  | 
|  2.0.8  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/cloudwatch-metrics-component.html)  | 
|  2.0.7  |  Version updated for Greengrass nucleus version 2.4.0 release.  | 
|  2.0.6  |  Version updated for Greengrass nucleus version 2.3.0 release.  | 
|  2.0.5  |  Version updated for Greengrass nucleus version 2.2.0 release.  | 
|  2.0.4  |  Version updated for Greengrass nucleus version 2.1.0 release.  | 
|  2.0.3  |  Initial version.  | 

------

## See also

+ [Using Amazon CloudWatch metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html) in the *Amazon CloudWatch User Guide*
+ [PutMetricData](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_PutMetricData.html) in the *Amazon CloudWatch API Reference*

# AWS IoT Device Defender


The AWS IoT Device Defender component (`aws.greengrass.DeviceDefender`) notifies administrators about changes in the state of Greengrass core devices. This can help identify unusual behavior that might indicate a compromised device. For more information, see [AWS IoT Device Defender](https://docs.aws.amazon.com/iot/latest/developerguide/device-defender.html) in the *AWS IoT Core Developer Guide*.

This component reads system metrics on the core device. Then, it publishes the metrics to AWS IoT Device Defender. For more information about how to read and interpret the metrics that this component reports, see [Device metrics document specification](https://docs.aws.amazon.com/iot/latest/developerguide/detect-device-side-metrics.html#DetectMetricsMessagesSpec) in the *AWS IoT Core Developer Guide*.

**Note**  
This component provides similar functionality to the Device Defender connector in AWS IoT Greengrass V1. For more information, see [Device Defender connector](https://docs.aws.amazon.com/greengrass/latest/developerguide/device-defender-connector.html) in the *AWS IoT Greengrass V1 Developer Guide*.

**Topics**
+ [

## Versions
](#device-defender-component-versions)
+ [

## Type
](#device-defender-component-type)
+ [

## Operating system
](#device-defender-component-os-support)
+ [

## Requirements
](#device-defender-component-requirements)
+ [

## Dependencies
](#device-defender-component-dependencies)
+ [

## Configuration
](#device-defender-component-configuration)
+ [

## Input data
](#device-defender-component-input-data)
+ [

## Output data
](#device-defender-component-output-data)
+ [

## Local log file
](#device-defender-component-log-file)
+ [

## Licenses
](#device-defender-component-licenses)
+ [

## Changelog
](#device-defender-component-changelog)

## Versions


This component has the following versions:
+ 3.1.x
+ 3.0.x
+ 2.0.x

For information about changes in each version of the component, see the [changelog](#device-defender-component-changelog).

## Type


------
#### [ v3.x ]

<a name="public-component-type-generic"></a>This <a name="public-component-type-generic-phrase"></a>component is a generic component (`aws.greengrass.generic`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs the component's lifecycle scripts.

------
#### [ v2.x ]

<a name="public-component-type-lambda"></a>This <a name="public-component-type-lambda-phrase"></a>component is a Lambda component (`aws.greengrass.lambda`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs this component's Lambda function using the [Lambda launcher component](lambda-launcher-component.md).

------

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


------
#### [ v3.x ]

This component can be installed on core devices that run the following operating systems:
+ Linux
+ Windows

------
#### [ v2.x ]

This component can be installed on Linux core devices only.

------

## Requirements


This component has the following requirements:

------
#### [ v3.x ]
+ <a name="public-component-python3-requirement"></a>[Python](https://www.python.org/) version 3.7 installed on the core device and added to the PATH environment variable.
+ AWS IoT Device Defender configured to use the Detect feature to monitor violations. For more information, see [Detect](https://docs.aws.amazon.com/iot/latest/developerguide/device-defender-detect.html) in the *AWS IoT Core Developer Guide*.

------
#### [ v2.x ]
+ <a name="core-device-lambda-function-requirements"></a>Your core device must meet the requirements to run Lambda functions. If you want the core device to run containerized Lambda functions, the device must meet the requirements to do so. For more information, see [Lambda function requirements](setting-up.md#greengrass-v2-lambda-requirements).
+ <a name="public-component-python3-requirement"></a>[Python](https://www.python.org/) version 3.7 installed on the core device and added to the PATH environment variable.
+ AWS IoT Device Defender configured to use the Detect feature to monitor violations. For more information, see [Detect](https://docs.aws.amazon.com/iot/latest/developerguide/device-defender-detect.html) in the *AWS IoT Core Developer Guide*.
+ The [psutil](https://pypi.org/project/psutil/) library installed on the core device. Version 5.7.0 is the latest version that is verified to work with the component.
+ The [cbor](https://pypi.org/project/cbor/) library installed on the core device. Version 1.0.0 is the latest version that is verified to work with the component.
+ <a name="connector-component-legacy-subscription-router-dependency"></a>To receive output data from this component, you must merge the following configuration update for the [legacy subscription router component](legacy-subscription-router-component.md) (`aws.greengrass.LegacySubscriptionRouter`) when you deploy this component. This configuration specifies the topic where this component publishes responses.

------
#### [ Legacy subscription router v2.1.x ]

  ```
  {
    "subscriptions": {
      "aws-greengrass-device-defender": {
        "id": "aws-greengrass-device-defender",
        "source": "component:aws.greengrass.DeviceDefender",
        "subject": "$aws/things/+/defender/metrics/json",
        "target": "cloud"
      }
    }
  }
  ```

------
#### [ Legacy subscription router v2.0.x ]

  ```
  {
    "subscriptions": {
      "aws-greengrass-device-defender": {
        "id": "aws-greengrass-device-defender",
        "source": "arn:aws:lambda:region:aws:function:aws-greengrass-device-defender:version",
        "subject": "$aws/things/+/defender/metrics/json",
        "target": "cloud"
      }
    }
  }
  ```<a name="connector-component-legacy-subscription-router-dependency-replace"></a>
  + Replace *region* with the AWS Region that you use.
  + Replace *version* with the version of the Lambda function that this component runs. To find the Lambda function version, you must view the recipe for the version of this component that you want to deploy. Open this component's details page in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass), and look for the **Lambda function** key-value pair. This key-value pair contains the name and version of the Lambda function.

**Important**  <a name="connector-component-legacy-subscription-router-dependency-note"></a>
You must update the Lambda function version on the legacy subscription router every time you deploy this component. This ensures that you use the correct Lambda function version for the component version that you deploy.

------

  <a name="connector-component-create-deployments"></a>For more information, see [Create deployments](create-deployments.md).

------

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#device-defender-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

------
#### [ 3.1.1 ]

The following table lists the dependencies for version 3.1.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <3.0.0 | Soft | 
| [Token exchange service](token-exchange-service-component.md) | >=0.0.0 | Hard | 

------
#### [ 3.0.0 - 3.0.2 ]

The following table lists the dependencies for versions 3.0.0 to 3.0.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <3.0.0 | Soft | 
| [Token exchange service](token-exchange-service-component.md) | >=0.0.0 | Hard | 

------
#### [ 2.0.12 - 2.0.17 ]

The following table lists the dependencies for version 2.0.12 to 2.0.17 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <3.0.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.0.12 - 2.0.16 ]

The following table lists the dependencies for version 2.0.16 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <3.0.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.0.10 - 2.0.11 ]

The following table lists the dependencies for version 2.0.10 and 2.0.11 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.8.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.0.9 ]

The following table lists the dependencies for version 2.0.9 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.7.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.0.8 ]

The following table lists the dependencies for version 2.0.8 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.6.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.0.7 ]

The following table lists the dependencies for version 2.0.7 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.5.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.0.6 ]

The following table lists the dependencies for version 2.0.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.4.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.0.5 ]

The following table lists the dependencies for version 2.0.5 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.3.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.0.4 ]

The following table lists the dependencies for version 2.0.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.2.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.0.3 ]

The following table lists the dependencies for version 2.0.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.3 <2.1.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | >=1.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | >=1.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | >=1.0.0  | Hard | 

------

For more information about component dependencies, see the [component recipe reference](component-recipe-reference.md#recipe-reference-component-dependencies).

## Configuration


This component provides the following configuration parameters that you can customize when you deploy the component.

------
#### [ v3.x ]

`PublishRetryCount`  
The amount of times the publish will be retried. This feature is available in version 3.1.1.  
The minimum is 0.  
The maximum is 72.  
Default: 5

`SampleIntervalSeconds`  
(Optional) The amount of time in seconds between each cycle where the component gathers and reports metrics.  
The minimum value is 300 seconds (5 minutes).  
Default: 300 seconds

 `UseInstaller`   
(Optional) Boolean value that defines whether to use the installer script in this component to install this component's dependencies.  
Set this value to `false` if you want to use a custom script to install dependencies, or if you want to include runtime dependencies in a pre-built Linux image. To use this component, you must install the following libraries, including any dependencies, and make them available to the default Greengrass system user.  
+ [AWS IoT Device SDK v2 for Python](https://github.com/aws/aws-iot-device-sdk-python-v2)
+ [cbor](https://pypi.org/project/cbor/) library. Version 1.0.0 is the latest version that is verified to work with the component.
+ [psutil](https://pypi.org/project/psutil/) library. Version 5.7.0 is the latest version that is verified to work with the component.
If you use version 3.0.0 or 3.0.1 of this component on core devices that you configure to use an HTTPS proxy, you must set this value to `false`. The installer script doesn't support operation behind an HTTPS proxy in these versions of this component.
Default: `true`

------
#### [ v2.x ]

**Note**  <a name="connector-component-lambda-parameters"></a>
This component's default configuration includes Lambda function parameters. We recommend that you edit only the following parameters to configure this component on your devices.

`lambdaParams`  
An object that contains the parameters for this component's Lambda function. This object contains the following information:    
`EnvironmentVariables`  
An object that contains the Lambda function's parameters. This object contains the following information:    
`PROCFS_PATH`  
(Optional) The path to the `/proc` folder.  
+ To run this component in a container, use the default value, `/host-proc`. The component runs in a container by default.
+ To run this component in no container mode, specify `/proc` for this parameter.
Default: `/host-proc`. This is the default path where this component mounts the `/proc` folder in the container.  
This component has read-only access to this folder.  
`SAMPLE_INTERVAL_SECONDS`  
(Optional) The amount of time in seconds between each cycle where the component gathers and reports metrics.  
The minimum value is 300 seconds (5 minutes).  
Default: 300 seconds

`containerMode`  
(Optional) The containerization mode for this component. Choose from the following options:  
+ `GreengrassContainer` – The component runs in an isolated runtime environment inside the AWS IoT Greengrass container.
+ `NoContainer` – The component doesn't run in an isolated runtime environment.

  If you specify this option, you must specify `/proc` for the `PROCFS_PATH` environment variable parameter.
Default: `GreengrassContainer`

`containerParams`  
<a name="connector-component-container-params-description"></a>(Optional) An object that contains the container parameters for this component. The component uses these parameters if you specify `GreengrassContainer` for `containerMode`.  
This object contains the following information:    
`memorySize`  
<a name="connector-component-container-params-memory-size-description"></a>(Optional) The amount of memory (in kilobytes) to allocate to the component.  
Defaults to 50,000 KB.

`pubsubTopics`  <a name="connector-component-pubsub-topics-parameter"></a>
(Optional) An object that contains the topics where the component subscribes to receive messages. You can specify each topic and whether the component subscribes to MQTT topics from AWS IoT Core or local publish/subscribe topics.  
This object contains the following information:    
`0` – This is an array index as a string.  
An object that contains the following information:    
`type`  
(Optional) The type of publish/subscribe messaging that this component uses to subscribe to messages. Choose from the following options:  
+ `PUB_SUB` – Subscribe to local publish/subscribe messages. If you choose this option, the topic can't contain MQTT wildcards. For more information about how to send messages from custom component when you specify this option, see [Publish/subscribe local messages](ipc-publish-subscribe.md).
+ `IOT_CORE` – Subscribe to AWS IoT Core MQTT messages. If you choose this option, the topic can contain MQTT wildcards. For more information about how to send messages from custom components when you specify this option, see [Publish/subscribe AWS IoT Core MQTT messages](ipc-iot-core-mqtt.md).
Default: `PUB_SUB`  
`topic`  
(Optional) The topic to which the component subscribes to receive messages. If you specify `IotCore` for `type`, you can use MQTT wildcards (`+` and `#`) in this topic.

**Example: Configuration merge update (container mode)**  

```
{
  "lambdaExecutionParameters": {
    "EnvironmentVariables": {
      "PROCFS_PATH": "/host_proc"
    }
  },
  "containerMode": "GreengrassContainer"
}
```

**Example: Configuration merge update (no container mode)**  

```
{
  "lambdaExecutionParameters": {
    "EnvironmentVariables": {
      "PROCFS_PATH": "/proc"
    }
  },
  "containerMode": "NoContainer"
}
```

------

## Input data


This component doesn't accept messages as input data.

## Output data


This component publishes security metrics to the following reserved topic for AWS IoT Device Defender. This component replaces *coreDeviceName* with the name of the core device when it publishes the metrics.

**Topic (AWS IoT Core MQTT):** `$aws/things/coreDeviceName/defender/metrics/json`

**Example output**  

```
{
  "header": {
    "report_id": 1529963534,
    "version": "1.0"
  },
  "metrics": {
    "listening_tcp_ports": {
      "ports": [
        {
          "interface": "eth0",
          "port": 24800
        },
        {
          "interface": "eth0",
          "port": 22
        },
        {
          "interface": "eth0",
          "port": 53
        }
      ],
      "total": 3
    },
    "listening_udp_ports": {
      "ports": [
        {
          "interface": "eth0",
          "port": 5353
        },
        {
          "interface": "eth0",
          "port": 67
        }
      ],
      "total": 2
    },
    "network_stats": {
      "bytes_in": 1157864729406,
      "bytes_out": 1170821865,
      "packets_in": 693092175031,
      "packets_out": 738917180
    },
    "tcp_connections": {
      "established_connections":{
        "connections": [
          {
            "local_interface": "eth0",
            "local_port": 80,
            "remote_addr": "192.168.0.1:8000"
          },
          {
            "local_interface": "eth0",
            "local_port": 80,
            "remote_addr": "192.168.0.1:8000"
          }
        ],
        "total": 2
      }
    }
  }
}
```

For more information about the metrics that this component reports, see [Device metrics document specification](https://docs.aws.amazon.com/iot/latest/developerguide/detect-device-side-metrics.html#DetectMetricsMessagesSpec) in the *AWS IoT Core Developer Guide*.

## Local log file


This component uses the following log file.

------
#### [ Linux ]

```
/greengrass/v2/logs/aws.greengrass.DeviceDefender.log
```

------
#### [ Windows ]

```
C:\greengrass\v2\logs\aws.greengrass.DeviceDefender.log
```

------

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the path to the AWS IoT Greengrass root folder.

------
#### [ Linux ]

  ```
  sudo tail -f /greengrass/v2/logs/aws.greengrass.DeviceDefender.log
  ```

------
#### [ Windows (PowerShell) ]

  ```
  Get-Content C:\greengrass\v2\logs\aws.greengrass.DeviceDefender.log -Tail 10 -Wait
  ```

------

## Licenses


<a name="component-core-software-license"></a>This component is released under the [Greengrass Core Software License Agreement](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf).

## Changelog


The following table describes the changes in each version of the component.

------
#### [ v3.x ]


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  3.1.1  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/device-defender-component.html)  | 
|  3.1.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/device-defender-component.html)  | 
|  3.0.1  |  Fixes an issue with how the component calculates delta values for metrics.  | 
|  3.0.0  |   This version is no longer available. The improvements in this version are available in later versions of this component.  Initial version.  | 

------
#### [ v2.x ]


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.0.17  |  Version updated for Greengrass nucleus version 2.14.0 release.  | 
|  2.0.16  |  Version updated for Greengrass nucleus version 2.13.0 release.  | 
|  2.0.11  |  Version updated for Greengrass nucleus version 2.11.0 release.  | 
|  2.0.10  |  Version updated for Greengrass nucleus version 2.7.0 release.  | 
|  2.0.9  |  Version updated for Greengrass nucleus version 2.6.0 release.  | 
|  2.0.8  |  Version updated for Greengrass nucleus version 2.5.0 release.  | 
|  2.0.7  |  Version updated for Greengrass nucleus version 2.4.0 release.  | 
|  2.0.6  |  Version updated for Greengrass nucleus version 2.3.0 release.  | 
|  2.0.5  |  Version updated for Greengrass nucleus version 2.2.0 release.  | 
|  2.0.4  |  Version updated for Greengrass nucleus version 2.1.0 release.  | 
|  2.0.3  |  Initial version.  | 

------

# Disk spooler
Disk spooler v1.0.5 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/disk-spooler-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/disk-spooler-component.html)

Disk spooler component v1.0.5 is available.Disk spooler v1.0.4 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/disk-spooler-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/disk-spooler-component.html)

Disk spooler component v1.0.4 is available.Disk spooler v1.0.3 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/disk-spooler-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/disk-spooler-component.html)

Disk spooler component v1.0.3 is available. This release improves performance by reusing database connections.Disk spooler v1.0.2 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/disk-spooler-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/disk-spooler-component.html)

Disk spooler component v1.0.2 is available. This release fixes an issue where the MQTT message format field isn't persisted in certain cases.Disk spooler v1.0.0 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/disk-spooler-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/disk-spooler-component.html)

Disk spooler component v1.0.0 is available.

The disk spooler component (`aws.greengrass.DiskSpooler`) offers a persistent storage option for messages spooled from Greengrass core devices to AWS IoT Core. This component will store these outbound messages on disk.

**Topics**
+ [

## Versions
](#disk-spooler-component-versions)
+ [

## Type
](#disk-spooler-component-type)
+ [

## Operating system
](#disk-spooler-component-os-support)
+ [

## Requirements
](#disk-spooler-component-requirements)
+ [

## Dependencies
](#disk-spooler-component-dependencies)
+ [

## Usage
](#disk-spooler-component-usage)
+ [

## Local log file
](#disk-spooler-component-log-file)
+ [

## Changelog
](#disk-spooler-component-changelog)

## Versions


This component has the following versions:
+ 1.0.x

## Type


<a name="public-component-type-plugin-para1"></a>This component is a plugin component (`aws.greengrass.plugin`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs this component in the same Java Virtual Machine (JVM) as the nucleus. The nucleus restarts when you change this component's version on the core device.

<a name="public-component-type-plugin-para2"></a>This component uses the same log file as the Greengrass nucleus. For more information, see [Monitor AWS IoT Greengrass logs](monitor-logs.md).

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on core devices that run the following operating systems:
+ Linux
+ Windows

## Requirements


This component has the following requirements:
+ `storageType` should be set to `Disk` to use this component. You can set this in the [Greengrass nucleus configuration](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration).
+ `maxSizeInBytes` must not be configured to be greater than the available space on the device. You can set this in the [Greengrass nucleus configuration](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration).
+ The disk spooler component is supported to run in a VPC.

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#disk-spooler-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

------
#### [ 1.0.7 ]

The following table lists the dependencies for version 1.0.7 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.11.0 <2.17.0 | Hard | 

------
#### [ 1.0. ]

The following table lists the dependencies for version 1.0.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.11.0 <2.16.0 | Hard | 

------
#### [ 1.0.5 ]

The following table lists the dependencies for version 1.0.5 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.11.0 <2.15.0 | Hard | 

------
#### [ 1.0.4 ]

The following table lists the dependencies for version 1.0.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.11.0 <2.14.0 | Hard | 

------
#### [ 1.0.1 – 1.0.3 ]

The following table lists the dependencies for versions 1.0.1 to 1.0.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.11.0 <2.13.0 | Hard | 

------
#### [ 1.0.0 ]

The following table lists the dependencies for version 1.0.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.11.0 <2.12.0 | Hard | 

------

For more information about component dependencies, see the [component recipe reference](component-recipe-reference.md#recipe-reference-component-dependencies).

## Usage


To use the disk spooler component, `aws.greengrass.DiskSpooler` must be deployed.

To configure and use this component, you must set the `pluginName` to `aws.greengrass.DiskSpooler`.

## Local log file


This component uses the same log file as the [Greengrass nucleus](greengrass-nucleus-component.md) component.

------
#### [ Linux ]

```
/greengrass/v2/logs/greengrass.log
```

------
#### [ Windows ]

```
C:\greengrass\v2\logs\greengrass.log
```

------

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the path to the AWS IoT Greengrass root folder.

------
#### [ Linux ]

  ```
  sudo tail -f /greengrass/v2/logs/greengrass.log
  ```

------
#### [ Windows (PowerShell) ]

  ```
  Get-Content C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
  ```

------

## Changelog


The following table describes the changes in each version of the component.


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  1.0.7  |  Version updated for Greengrass nucleus version 2.16.0 release.  | 
|  1.0.6  |  Version updated for Greengrass nucleus version 2.15.0 release.  | 
|  1.0.5  |  Version updated for Greengrass nucleus version 2.14.0 release.  | 
|  1.0.4  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/disk-spooler-component.html)  | 
|  1.0.3  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/disk-spooler-component.html)  | 
|  1.0.2  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/disk-spooler-component.html)  | 
|  1.0.1  |  Version updated for Greengrass nucleus version 2.12.0 release.  | 
|  1.0.0  |  Initial version.  | 

# Docker application manager


The Docker application manager component (`aws.greengrass.DockerApplicationManager`) enables AWS IoT Greengrass to download Docker images from public image registries and private registries hosted on Amazon Elastic Container Registry (Amazon ECR). It also enables AWS IoT Greengrass to manage credentials automatically to securely download images from private repositories in Amazon ECR.

When you develop a custom component that runs a Docker container, include the Docker application manager as a dependency to download the Docker images that are specified as artifacts in your component. For more information, see [Run a Docker container](run-docker-container.md).

**Topics**
+ [

## Versions
](#docker-application-manager-component-versions)
+ [

## Type
](#docker-application-manager-component-type)
+ [

## Operating system
](#docker-application-manager-component-os-support)
+ [

## Requirements
](#docker-application-manager-component-requirements)
+ [

## Dependencies
](#docker-application-manager-component-dependencies)
+ [

## Configuration
](#docker-application-manager-component-configuration)
+ [

## Local log file
](#docker-application-manager-component-log-file)
+ [

## Changelog
](#docker-application-manager-component-changelog)
+ [

## See also
](#docker-application-manager-component-see-also)

## Versions


This component has the following versions:
+ 2.0.x

## Type


<a name="public-component-type-generic"></a>This <a name="public-component-type-generic-phrase"></a>component is a generic component (`aws.greengrass.generic`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs the component's lifecycle scripts.

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on core devices that run the following operating systems:
+ Linux
+ Windows

## Requirements


This component has the following requirements:
+ <a name="docker-engine-requirement"></a>[Docker Engine](https://docs.docker.com/engine/) 1.9.1 or later installed on the Greengrass core device. Version 20.10 is the latest version that is verified to work with the AWS IoT Greengrass Core software. You must install Docker directly on the core device before you deploy components that run Docker containers.
+ <a name="docker-daemon-requirement"></a>The Docker daemon started and running on the core device before you deploy this component. 
+ Docker images stored in one of the following supported image sources:
  + Public and private image repositories in Amazon Elastic Container Registry (Amazon ECR)
  + Public Docker Hub repository
  + Public Docker Trusted Registry
+ Docker images included as artifacts in your custom Docker container components. Use the following URI formats to specify your Docker images:<a name="docker-image-artifact-uri"></a>
  + Private Amazon ECR image: `docker:account-id.dkr.ecr.region.amazonaws.com/repository/image[:tag|@digest]`
  + Public Amazon ECR image: `docker:public.ecr.aws/repository/image[:tag|@digest]`
  + Public Docker Hub image: `docker:name[:tag|@digest]`

  For more information, see [Run a Docker container](run-docker-container.md).
**Note**  
If you don't specify the image tag or image digest in the artifact URI for an image, then the Docker application manager pulls the latest available version of that image when you deploy your custom Docker container component. To ensure that all of your core devices run the same version of an image, we recommend that you include the image tag or image digest in the artifact URI.
+ <a name="docker-user-permissions-requirement"></a>The system user that runs a Docker container component must have root or administrator permissions, or you must configure Docker to run it as a non-root or non-admistrator user.
  + On Linux devices, you can add a user to the `docker` group to call `docker` commands without `sudo`.
  + On Windows devices, you can add a user to the `docker-users` group to call `docker` commands without adminstrator privileges.

------
#### [ Linux or Unix ]

  To add `ggc_user`, or the non-root user that you use to run Docker container components, to the `docker` group, run the following command.

  ```
  sudo usermod -aG docker ggc_user
  ```

  For more information, see [Manage Docker as a non-root user](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user).

------
#### [ Windows Command Prompt (CMD) ]

  To add `ggc_user`, or the user that you use to run Docker container components, to the `docker-users` group, run the following command as an administrator.

  ```
  net localgroup docker-users ggc_user /add
  ```

------
#### [ Windows PowerShell ]

  To add `ggc_user`, or the user that you use to run Docker container components, to the `docker-users` group, run the following command as an administrator.

  ```
  Add-LocalGroupMember -Group docker-users -Member ggc_user
  ```

------
+ <a name="docker-proxy-requirement"></a>If you [configure the AWS IoT Greengrass Core software to use a network proxy](configure-greengrass-core-v2.md#configure-alpn-network-proxy), you must [configure Docker to use the same proxy server](https://docs.docker.com/network/proxy/).
+ If your Docker images are stored in an Amazon ECR private registry, then you must include the token exchange service component as a dependency in the Docker container component. Also, the [Greengrass device role](device-service-role.md) must allow the `ecr:GetAuthorizationToken`, `ecr:BatchGetImage`, and `ecr:GetDownloadUrlForLayer` actions, as shown in the following example IAM policy.

------
#### [ JSON ]

****  

  ```
  {
    "Version":"2012-10-17",		 	 	 
    "Statement": [
      {
        "Action": [
          "ecr:GetAuthorizationToken",
          "ecr:BatchGetImage",
          "ecr:GetDownloadUrlForLayer"
        ],
        "Resource": [
          "*"
        ],
        "Effect": "Allow"
      }
    ]
  }
  ```

------

  ```
  ```
+ The docker application manager component is supported to run in a VPC. To deploy this component in a VPC, the following is required.
  + The docker application manager component must have connectivity to download images. For example, if you use ECR, you must have connectivity to the following endpoints.
    + `*.dkr.ecr.region.amazonaws.com` (VPC endpoint `com.amazonaws.region.ecr.dkr`)
    + `api.ecr.region.amazonaws.com` (VPC endpoint `com.amazonaws.region.ecr.api`)

### Endpoints and ports


This component must be able to perform outbound requests to the following endpoints and ports, in addition to endpoints and ports required for basic operation. For more information, see [Allow device traffic through a proxy or firewall](allow-device-traffic.md).


| Endpoint | Port | Required | Description | 
| --- | --- | --- | --- | 
|  `ecr.region.amazonaws.com`  | 443 | No |  Required if you download Docker images from Amazon ECR.  | 
|  `hub.docker.com` `registry.hub.docker.com/v1`  | 443 | No |  Required if you download Docker images from Docker Hub.  | 

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#docker-application-manager-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

------
#### [ 2.0.15 ]

The following table lists the dependencies for version 2.0.15 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.17.0 | Soft | 

------
#### [ 2.0.14 ]

The following table lists the dependencies for version 2.0.14 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.16.0 | Soft | 

------
#### [ 2.0.13 ]

The following table lists the dependencies for version 2.0.13 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.15.0 | Soft | 

------
#### [ 2.0.12 ]

The following table lists the dependencies for version 2.0.12 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.14.0 | Soft | 

------
#### [ 2.0.11 ]

The following table lists the dependencies for version 2.0.11 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.13.0 | Soft | 

------
#### [ 2.0.10 ]

The following table lists the dependencies for version 2.0.10 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.12.0 | Soft | 

------
#### [ 2.0.9 ]

The following table lists the dependencies for version 2.0.9 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.11.0 | Soft | 

------
#### [ 2.0.8 ]

The following table lists the dependencies for version 2.0.8 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.10.0 | Soft | 

------
#### [ 2.0.7 ]

The following table lists the dependencies for version 2.0.7 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.9.0 | Soft | 

------
#### [ 2.0.6 ]

The following table lists the dependencies for version 2.0.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.8.0 | Soft | 

------
#### [ 2.0.5 ]

The following table lists the dependencies for version 2.0.5 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.7.0 | Soft | 

------
#### [ 2.0.4 ]

The following table lists the dependencies for version 2.0.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.6.0 | Soft | 

------
#### [ 2.0.3 ]

The following table lists the dependencies for version 2.0.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.5.0 | Soft | 

------
#### [ 2.0.2 ]

The following table lists the dependencies for version 2.0.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.4.0 | Soft | 

------
#### [ 2.0.1 ]

The following table lists the dependencies for version 2.0.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.3.0 | Soft | 

------
#### [ 2.0.0 ]

The following table lists the dependencies for version 2.0.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.2.0 | Soft | 

------

For more information about component dependencies, see the [component recipe reference](component-recipe-reference.md#recipe-reference-component-dependencies).

## Configuration


This component doesn't have any configuration parameters.

## Local log file


This component uses the same log file as the [Greengrass nucleus](greengrass-nucleus-component.md) component.

------
#### [ Linux ]

```
/greengrass/v2/logs/greengrass.log
```

------
#### [ Windows ]

```
C:\greengrass\v2\logs\greengrass.log
```

------

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the path to the AWS IoT Greengrass root folder.

------
#### [ Linux ]

  ```
  sudo tail -f /greengrass/v2/logs/greengrass.log
  ```

------
#### [ Windows (PowerShell) ]

  ```
  Get-Content C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
  ```

------

## Changelog


The following table describes the changes in each version of the component.


|   **Version**   |   **Changes**   | 
| --- | --- | 
|  2.0.15  |  Version updated for Greengrass nucleus version 2.16.0 release.  | 
|  2.0.14  | Version updated for Greengrass nucleus version 2.15.0 release. | 
|  2.0.13  | Version updated for Greengrass nucleus version 2.14.0 release. | 
|  2.0.12  | Version updated for Greengrass nucleus version 2.13.0 release. | 
|  2.0.11  | Version updated for Greengrass nucleus version 2.12.0 release. | 
|  2.0.10  | Version updated for Greengrass nucleus version 2.11.0 release. | 
|  2.0.9  | Version updated for Greengrass nucleus version 2.10.0 release. | 
|  2.0.8  | Version updated for Greengrass nucleus version 2.9.0 release. | 
|  2.0.7  | Version updated for Greengrass nucleus version 2.8.0 release. | 
|  2.0.6  |  Version updated for Greengrass nucleus version 2.7.0 release.  | 
|  2.0.5  |  Version updated for Greengrass nucleus version 2.6.0 release.  | 
|  2.0.4  |  Version updated for Greengrass nucleus version 2.5.0 release.  | 
|  2.0.3  |  Version updated for Greengrass nucleus version 2.4.0 release.  | 
|  2.0.2  |  Version updated for Greengrass nucleus version 2.3.0 release.  | 
|  2.0.1  |  Version updated for Greengrass nucleus version 2.2.0 release.  | 
|  2.0.0  |  Initial version.  | 

## See also

+  [Run a Docker container](run-docker-container.md) 

# Edge connector for Kinesis Video Streams
Edge connector for Kinesis Video Streams component v1.0.5 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/kvs-edge-connector-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/kvs-edge-connector-component.html)

Version 1.0.5 of the edge connector for Kinesis Video Streams component is available. This version includes general bug fixes and improvements.New edge connector for Kinesis Video Streams component[https://docs.aws.amazon.com/greengrass/v2/developerguide/kvs-edge-connector-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/kvs-edge-connector-component.html)

Version 1.0.0 of the edge connector for Kinesis Video Streams component is available. This AWS-provided reads video feeds from local cameras and publishes the streams to Kinesis Video Streams. This component integrates with AWS IoT TwinMaker, which enables you to view and manage video streams and other data in Grafana dashboards.

The edge connector for Kinesis Video Streams component (`aws.iot.EdgeConnectorForKVS`) reads video feeds from local cameras and publishes the streams to Kinesis Video Streams. You can configure this component to read video feeds from Internet Protocol (IP) cameras using Real Time Streaming Protocol (RTSP). Then, you can set up dashboards in [Amazon Managed Grafana](https://docs.aws.amazon.com/grafana/latest/userguide/what-is-Amazon-Managed-Service-Grafana.html) or local Grafana servers to monitor and interact with the video streams.

You can integrate this component with AWS IoT TwinMaker to display and control video streams in Grafana dashboards. AWS IoT TwinMaker is an AWS service that enables you to build operational digital twins of physical systems. You can use AWS IoT TwinMaker to visualize data from sensors, cameras, and enterprise applications for you to track your physical factories, buildings, or industrial plants. You can also use this data to monitor operations, diagnose errors, and repair errors. For more information, see [What is AWS IoT TwinMaker?](https://docs.aws.amazon.com/iot-twinmaker/latest/guide/what-is-twinmaker.html) in the *AWS IoT TwinMaker User Guide*.

This component stores its configuration in AWS IoT SiteWise, which is an AWS service that models and stores industrial data. In AWS IoT SiteWise, *assets* represent objects such as devices, equipment, or groups of other objects. To configure and use this component, you create an AWS IoT SiteWise asset for each Greengrass core device and for each IP camera connected to each core device. Each asset has properties that you configure to control features, such as live streaming, on-demand upload, and local caching. To specify the URL for each camera, you create a secret in AWS Secrets Manager that contains the URL of the camera. If the camera requires authentication, you also specify a user name and password in the URL. Then, you specify that secret in an asset property for the IP camera.

This component uploads each camera's video stream to a Kinesis video stream. You specify the name of the destination Kinesis video stream in the AWS IoT SiteWise asset configuration for each camera. If the Kinesis video stream doesn't exist, this component creates it for you.

AWS IoT TwinMaker provides a script that you can run to create these AWS IoT SiteWise assets and Secrets Manager secrets. For more information about how to create these resources, and how to install, configure, and use this component, see [AWS IoT TwinMaker video integration](https://docs.aws.amazon.com/iot-twinmaker/latest/guide/video-integration.html) in the *AWS IoT TwinMaker User Guide*.

**Note**  
The edge connector for Kinesis Video Streams component is available only in the following AWS Regions:  
US East (N. Virginia)
US West (Oregon)
Europe (Frankfurt)
Europe (Ireland)
Asia Pacific (Singapore)
Asia Pacific (Tokyo)
Asia Pacific (Seoul)
Asia Pacific (Sydney)
Asia Pacific (Mumbai)
China (Beijing)

**Topics**
+ [

## Versions
](#kvs-edge-connector-component-versions)
+ [

## Type
](#kvs-edge-connector-component-type)
+ [

## Operating system
](#kvs-edge-connector-component-os-support)
+ [

## Requirements
](#kvs-edge-connector-component-requirements)
+ [

## Dependencies
](#kvs-edge-connector-component-dependencies)
+ [

## Configuration
](#kvs-edge-connector-component-configuration)
+ [

## Licenses
](#kvs-edge-connector-component-licenses)
+ [

## Usage
](#kvs-edge-connector-component-usage)
+ [

## Local log file
](#kvs-edge-connector-component-log-file)
+ [

## Changelog
](#kvs-edge-connector-component-changelog)
+ [

## See also
](#kvs-edge-connector-component-see-also)

## Versions


This component has the following versions:
+ 1.0.x

## Type


<a name="public-component-type-generic"></a>This <a name="public-component-type-generic-phrase"></a>component is a generic component (`aws.greengrass.generic`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs the component's lifecycle scripts.

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on Linux core devices only.

## Requirements


This component has the following requirements:
+ You can deploy this component to only single core devices, because the component configuration must be unique for each core device. You can't deploy this component to groups of core devices.
+ [GStreamer](https://gstreamer.freedesktop.org) 1.18.4 or later installed on the core device. For more information, see [Installing GStreamer](https://gstreamer.freedesktop.org/documentation/installing/index.html?gi-language=c).

  On a device with `apt`, you can run the following commands to install GStreamer.

  ```
  sudo apt install -y libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev gstreamer1.0-plugins-base-apps
  sudo apt install -y gstreamer1.0-libav
  sudo apt install -y gstreamer1.0-plugins-bad gstreamer1.0-plugins-good gstreamer1.0-plugins-ugly gstreamer1.0-tools
  ```
+ An AWS IoT SiteWise asset for each core device. This AWS IoT SiteWise asset represents the core device. For more information about how to create this asset, see [AWS IoT TwinMaker video integration](https://docs.aws.amazon.com/iot-twinmaker/latest/guide/video-integration.html) in the *AWS IoT TwinMaker User Guide*.
+ An AWS IoT SiteWise asset for each IP camera that you connect to each core device. These AWS IoT SiteWise assets represent the cameras that stream video to each core device. Each camera's asset must be associated to the asset for the core device that connects to the camera. Camera assets have properties that you can configure to specify a Kinesis video stream, an authentication secret, and video streaming parameters. For more information about how to create and configure camera assets, see [AWS IoT TwinMaker video integration](https://docs.aws.amazon.com/iot-twinmaker/latest/guide/video-integration.html) in the *AWS IoT TwinMaker User Guide*.
+ An AWS Secrets Manager secret for each IP camera. This secret must define a key-value pair, where the key is `RTSPStreamUrl`, and the value is the URL for the camera. If the camera requires authentication, include the user name and password in this URL. You can use a script to create a secret when you create the resources that this component requires. For more information, see [AWS IoT TwinMaker video integration](https://docs.aws.amazon.com/iot-twinmaker/latest/guide/video-integration.html) in the *AWS IoT TwinMaker User Guide*.

  You can also use the Secrets Manager console and API to create additional secrets. For more information, see [Create a secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html) in the *AWS Secrets Manager User Guide*.
+ The [Greengrass token exchange role](device-service-role.md) must allow the following AWS Secrets Manager, AWS IoT SiteWise, and Kinesis Video Streams actions, as shown in the following example IAM policy.
**Note**  
This example policy allows the device to get the value of secrets named **IPCamera1Url** and **IPCamera2Url**. When you configure each IP camera, you specify a secret that contains the URL for that camera. If the camera requires authentication, you also specify a user name and password in the URL. The core device's token exchange role must allow access to the secret for each IP camera to connect.

------
#### [ JSON ]

****  

  ```
  {
    "Version":"2012-10-17",		 	 	 
    "Statement": [
      {
        "Action": [
          "secretsmanager:GetSecretValue"
        ],
        "Effect": "Allow",
        "Resource": [
        "arn:aws:secretsmanager:us-east-1:123456789012:secret:IPCamera1Url",
    "arn:aws:secretsmanager:us-east-1:123456789012:secret:IPCamera2Url"
        ]
      },
      {
        "Action": [
          "iotsitewise:BatchPutAssetPropertyValue",
          "iotsitewise:DescribeAsset",
          "iotsitewise:DescribeAssetModel",
          "iotsitewise:DescribeAssetProperty",
          "iotsitewise:GetAssetPropertyValue",
          "iotsitewise:ListAssetRelationships",
          "iotsitewise:ListAssets",
          "iotsitewise:ListAssociatedAssets",
          "kinesisvideo:CreateStream",
          "kinesisvideo:DescribeStream",
          "kinesisvideo:GetDataEndpoint",
          "kinesisvideo:PutMedia",
          "kinesisvideo:TagStream"
        ],
        "Effect": "Allow",
        "Resource": [
          "*"
        ]
      }
    ]
  }
  ```

------
**Note**  
If you use a customer managed AWS Key Management Service key to encrypt secrets, the device role must also allow the `kms:Decrypt` action.

### Endpoints and ports


This component must be able to perform outbound requests to the following endpoints and ports, in addition to endpoints and ports required for basic operation. For more information, see [Allow device traffic through a proxy or firewall](allow-device-traffic.md).


| Endpoint | Port | Required | Description | 
| --- | --- | --- | --- | 
|  `kinesisvideo.region.amazonaws.com`  | 443 | Yes |  Upload data to Kinesis Video Streams.  | 
|  `data.iotsitewise.region.amazonaws.com`  | 443 | Yes |  Publish video stream metadata to AWS IoT SiteWise.  | 
|  `secretsmanager.region.amazonaws.com`  | 443 | Yes |  Download camera URL secrets to the core device.  | 

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#kvs-edge-connector-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

The following table lists the dependencies for versions 1.0.0 to 1.0.5 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Token exchange service](token-exchange-service-component.md) | >=2.0.3 | Hard | 
| [Stream manager](stream-manager-component.md) | >=2.0.9 | Hard | 

For more information about component dependencies, see the [component recipe reference](component-recipe-reference.md#recipe-reference-component-dependencies).

## Configuration


This component provides the following configuration parameters that you can customize when you deploy the component.

`SiteWiseAssetIdForHub`  
The ID of the AWS IoT SiteWise asset that represents this core device. For more information about how to create this asset and use it to interact with this component, see [AWS IoT TwinMaker video integration](https://docs.aws.amazon.com/iot-twinmaker/latest/guide/video-integration.html) in the *AWS IoT TwinMaker User Guide*.

**Example: Configuration merge update**  

```
{
  "SiteWiseAssetIdForHub": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
}
```

## Licenses


This component includes the following third-party software/licensing:
+ [Quartz Job Scheduler](http://www.quartz-scheduler.org/) / Apache License 2.0
+ [Java bindings for GStreamer 1.x](https://github.com/gstreamer-java/gst1-java-core) / GNU Lesser General Public License v3.0

## Usage


To configure and interact with this component, you can set properties on the AWS IoT SiteWise assets that represent the core device and the IP cameras where it connects. You can also visualize and interact with video streams in Grafana dashboards through AWS IoT TwinMaker. For more information, see [AWS IoT TwinMaker video integration](https://docs.aws.amazon.com/iot-twinmaker/latest/guide/video-integration.html) in the *AWS IoT TwinMaker User Guide*.

## Local log file


This component uses the following log file.

```
/greengrass/v2/logs/aws.iot.EdgeConnectorForKVS.log
```

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` with the path to the AWS IoT Greengrass root folder.

  ```
  sudo tail -f /greengrass/v2/logs/aws.iot.EdgeConnectorForKVS.log
  ```

## Changelog


The following table describes the changes in each version of the component.


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  1.0.5  |  General bug fixes and improvements.  | 
|  1.0.4  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/kvs-edge-connector-component.html)  | 
|  1.0.3  |  General bug fixes and improvements.  | 
|  1.0.1  |  General bug fixes and improvements.  | 
|  1.0.0  |  Initial version.  | 

## See also

+ [What is AWS IoT TwinMaker?](https://docs.aws.amazon.com/iot-twinmaker/latest/guide/what-is-twinmaker.html) in the *AWS IoT TwinMaker User Guide*
+ [AWS IoT TwinMaker video integration](https://docs.aws.amazon.com/iot-twinmaker/latest/guide/video-integration.html) in the *AWS IoT TwinMaker User Guide*
+ [What is AWS IoT SiteWise?](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/what-is-sitewise.html) in the *AWS IoT SiteWise User Guide*
+ [Updating attribute values](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/update-attribute-values.html) in the *AWS IoT SiteWise User Guide*
+ [What is AWS Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) in the *AWS Secrets Manager User Guide*
+ [Create and manage secrets](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets.html) in the *AWS Secrets Manager User Guide*

# Greengrass CLI
Greengrass CLI v2.16.1 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-cli-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-cli-component.html)

Greengrass CLI component v2.16.1 is available.Greengrass CLI v2.16.0 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-cli-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-cli-component.html)

Greengrass CLI component v2.16.0 is available.Greengrass CLI v2.14.3 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-cli-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-cli-component.html)

Greengrass CLI component v2.14.3 is available.Greengrass CLI v2.14.2 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-cli-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-cli-component.html)

Greengrass CLI component v2.14.2 is available.Greengrass CLI v2.14.1 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-cli-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-cli-component.html)

Greengrass CLI component v2.14.1 is available.Greengrass CLI v2.14.0 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-cli-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-cli-component.html)

Greengrass CLI component v2.14.0 is available.Greengrass CLI v2.13.0 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-cli-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-cli-component.html)

Greengrass CLI component v2.13.0 is available.Greengrass CLI v2.12.6 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-cli-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-cli-component.html)

Greengrass CLI component v2.12.6 is available.Greengrass CLI v2.12.5 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-cli-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-cli-component.html)

Greengrass CLI component v2.12.5 is available.Greengrass CLI v2.12.4 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-cli-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-cli-component.html)

Greengrass CLI component v2.12.4 is available.Greengrass CLI v2.12.3 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-cli-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-cli-component.html)

Greengrass CLI component v2.12.3 is available.Greengrass CLI v2.12.0 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-cli-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-cli-component.html)

Greengrass CLI component v2.12.0 is available.Greengrass CLI v2.11.3 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-cli-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-cli-component.html)

Greengrass CLI component v2.11.3 is available.

The Greengrass CLI component (`aws.greengrass.Cli`) provides a local command-line interface that you can use on core devices to develop and debug components locally. The Greengrass CLI lets you create local deployments and restart components on the core device, for example.

You can install this component when you install the AWS IoT Greengrass Core software. For more information, see [Tutorial: Getting started with AWS IoT Greengrass V2](getting-started.md).

**Important**  
 <a name="local-dev-tools-production-environment-warning"></a>We recommend that you use this component in only development environments, not production environments. This component provides access to information and operations that you typically won't need in a production environment. Follow the principle of least privilege by deploying this component to only core devices where you need it. 

After you install this component, run the following command to view its help documentation. When this component installs, it adds a symbolic link to `greengrass-cli` in the `/greengrass/v2/bin` folder. You can run the Greengrass CLI from this path or add it to your `PATH` environment variable to run `greengrass-cli` without its absolute path.

------
#### [ Linux or Unix ]

```
/greengrass/v2/bin/greengrass-cli help
```

------
#### [ Windows ]

```
C:\greengrass\v2\bin\greengrass-cli help
```

------

The following command restarts a component named `com.example.HelloWorld`, for example.

------
#### [ Linux or Unix ]

```
sudo /greengrass/v2/bin/greengrass-cli component restart --names "com.example.HelloWorld"
```

------
#### [ Windows ]

```
C:\greengrass\v2\bin\greengrass-cli component restart --names "com.example.HelloWorld"
```

------

For more information, see [Greengrass Command Line Interface](gg-cli.md).

**Topics**
+ [

## Versions
](#greengrass-cli-component-versions)
+ [

## Type
](#greengrass-cli-component-type)
+ [

## Operating system
](#greengrass-cli-component-os-support)
+ [

## Requirements
](#greengrass-cli-component-requirements)
+ [

## Dependencies
](#greengrass-cli-component-dependencies)
+ [

## Configuration
](#greengrass-cli-component-configuration)
+ [

## Local log file
](#greengrass-cli-component-log-file)
+ [

## Changelog
](#greengrass-cli-component-changelog)

## Versions


This component has the following versions:
+ 2.16.x
+ 2.15.x
+ 2.14.x
+ 2.13.x
+ 2.12.x
+ 2.11.x
+ 2.10.x
+ 2.9.x
+ 2.8.x
+ 2.7.x
+ 2.6.x
+ 2.5.x
+ 2.4.x
+ 2.3.x
+ 2.2.x
+ 2.1.x
+ 2.0.x

## Type


<a name="public-component-type-plugin-para1"></a>This component is a plugin component (`aws.greengrass.plugin`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs this component in the same Java Virtual Machine (JVM) as the nucleus. The nucleus restarts when you change this component's version on the core device.

<a name="public-component-type-plugin-para2"></a>This component uses the same log file as the Greengrass nucleus. For more information, see [Monitor AWS IoT Greengrass logs](monitor-logs.md).

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on core devices that run the following operating systems:
+ Linux
+ Windows

## Requirements


This component has the following requirements:
+ <a name="greengrass-cli-authorization-requirement"></a>You must be authorized to use the Greengrass CLI to interact with the AWS IoT Greengrass Core software. Do one of the following to use the Greengrass CLI:
  + Use the system user that runs the AWS IoT Greengrass Core software.
  + Use a user with root or adminstrative permissions. On Linux core devices, you can use `sudo` to gain root permissions.
  + Use a system user that's in a group that you specify in the `AuthorizedPosixGroups` or `AuthorizedWindowsGroups` configuration parameters when you deploy the component. For more information, see [Greengrass CLI component configuration](#greengrass-cli-component-configuration).
+ The Greengrass CLI component is supported to run in a VPC.

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#greengrass-cli-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

------
#### [ 2.16.0 ]

The following table lists the dependencies for version 2.16.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.12.0 <2.17.0 | Soft | 

------
#### [ 2.15.1 ]

The following table lists the dependencies for version 2.15.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.12.0 <2.16.0 | Soft | 

------
#### [ 2.15.0 ]

The following table lists the dependencies for version 2.15.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.12.0 <2.16.0 | Soft | 

------
#### [ 2.14.0 – 2.14.3 ]

The following table lists the dependencies for versions 2.14.0 and 2.14.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.12.0 <2.15.0 | Soft | 

------
#### [ 2.13.0 ]

The following table lists the dependencies for version 2.13.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.12.0 <2.14.0 | Soft | 

------
#### [ 2.12.0 – 2.12.6 ]

The following table lists the dependencies for version 2.12.0 through 2.12.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.12.0 <2.13.0 | Soft | 

------
#### [ 2.11.0 – 2.11.3 ]

The following table lists the dependencies for versions 2.11.0 through 2.11.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.11.0 <2.12.0 | Soft | 

------
#### [ 2.10.0 – 2.10.3 ]

The following table lists the dependencies for versions 2.10.0 through 2.10.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.0 <2.11.0 | Soft | 

------
#### [ 2.9.0 – 2.9.6 ]

The following table lists the dependencies for versions 2.9.0 through 2.9.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.0 <2.10.0 | Soft | 

------
#### [ 2.8.0 – 2.8.1 ]

The following table lists the dependencies for version 2.8.0 and 2.8.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.0 <2.9.0 | Soft | 

------
#### [ 2.7.0 ]

The following table lists the dependencies for version 2.7.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.0 <2.8.0 | Soft | 

------
#### [ 2.6.0 ]

The following table lists the dependencies for version 2.6.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.0 <2.7.0 | Soft | 

------
#### [ 2.5.0 – 2.5.6 ]

The following table lists the dependencies for versions 2.5.0 through 2.5.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.0 <2.6.0 | Soft | 

------
#### [ 2.4.0 ]

The following table lists the dependencies for version 2.4.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.5.0 | Soft | 

------
#### [ 2.3.0 ]

The following table lists the dependencies for version 2.3.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.4.0 | Soft | 

------
#### [ 2.2.0 ]

The following table lists the dependencies for version 2.2.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.3.0 | Soft | 

------
#### [ 2.1.0 ]

The following table lists the dependencies for version 2.1.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.2.0 | Soft | 

------
#### [ 2.0.x ]

The following table lists the dependencies for version 2.0.x of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.1.0 | Soft | 

**Note**  
The minimum compatible version of the Greengrass nucleus corresponds to the patch version of the Greengrass CLI component. 

------

For more information about component dependencies, see the [component recipe reference](component-recipe-reference.md#recipe-reference-component-dependencies).

## Configuration


This component provides the following configuration parameters that you can customize when you deploy the component.

------
#### [ 2.5.x - 2.14.x ]

`AuthorizedPosixGroups`  <a name="greengrass-cli-component-configuration-authorizedposixgroups"></a>
(Optional) A string that contains a comma-separated list of system groups. You authorize these system groups to use the Greengrass CLI to interact with the AWS IoT Greengrass Core software. You can specify group names or group IDs. For example, `group1,1002,group3` authorizes three system groups (`group1`, `1002`, and `group3`) to use the Greengrass CLI.  
If you don't specify any groups to authorize, you can use the Greengrass CLI as the root user (`sudo`) or as the system user that runs the AWS IoT Greengrass Core software.

`AuthorizedWindowsGroups`  <a name="greengrass-cli-component-configuration-authorizedwindowsgroups"></a>
(Optional) A string that contains a comma-separated list of system groups. You authorize these system groups to use the Greengrass CLI to interact with the AWS IoT Greengrass Core software. You can specify group names or group IDs. For example, `group1,1002,group3` authorizes three system groups (`group1`, `1002`, and `group3`) to use the Greengrass CLI.  
If you don't specify any groups to authorize, you can use the Greengrass CLI as an administrator or as the system user that runs the AWS IoT Greengrass Core software.

**Example: Configuration merge update**  
The following example configuration specifies to authorize three POSIX system groups (`group1`, `1002`, and `group3`) and two Windows user groups (`Device Operators` and `QA Engineers`) to use the Greengrass CLI.  

```
{
  "AuthorizedPosixGroups": "group1,1002,group3",
  "AuthorizedWindowsGroups": "Device Operators,QA Engineers"
}
```

------
#### [ 2.4.x - 2.0.x ]

`AuthorizedPosixGroups`  <a name="greengrass-cli-component-configuration-authorizedposixgroups"></a>
(Optional) A string that contains a comma-separated list of system groups. You authorize these system groups to use the Greengrass CLI to interact with the AWS IoT Greengrass Core software. You can specify group names or group IDs. For example, `group1,1002,group3` authorizes three system groups (`group1`, `1002`, and `group3`) to use the Greengrass CLI.  
If you don't specify any groups to authorize, you can use the Greengrass CLI as the root user (`sudo`) or as the system user that runs the AWS IoT Greengrass Core software.

**Example: Configuration merge update**  
The following example configuration specifies to authorize three system groups (`group1`, `1002`, and `group3`) to use the Greengrass CLI.  

```
{
  "AuthorizedPosixGroups": "group1,1002,group3"
}
```

------

## Local log file


This component uses the same log file as the [Greengrass nucleus](greengrass-nucleus-component.md) component.

------
#### [ Linux ]

```
/greengrass/v2/logs/greengrass.log
```

------
#### [ Windows ]

```
C:\greengrass\v2\logs\greengrass.log
```

------

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the path to the AWS IoT Greengrass root folder.

------
#### [ Linux ]

  ```
  sudo tail -f /greengrass/v2/logs/greengrass.log
  ```

------
#### [ Windows (PowerShell) ]

  ```
  Get-Content C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
  ```

------

## Changelog


The following table describes the changes in each version of the component.


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.16.1  |  Version updated for Greengrass nucleus version 2.16.1 release.  | 
|  2.16.0  |  Version updated for Greengrass nucleus version 2.16.0 release.  | 
|  2.15.1  |  Version updated for Greengrass nucleus version 2.15.1 release.  | 
|  2.15.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-cli-component.html)  | 
|  2.14.3  |  Version updated for Greengrass nucleus version 2.14.3 release.  | 
|  2.14.2  |  Version updated for Greengrass nucleus version 2.14.2 release.  | 
|  2.14.1  |  Version updated for Greengrass nucleus version 2.14.1 release.  | 
|  2.14.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-cli-component.html)  | 
|  2.13.0  |  Version updated for Greengrass nucleus version 2.13.0 release.  | 
|  2.12.6  |  Version updated for Greengrass nucleus version 2.12.6 release.  | 
|  2.12.5  |  Version updated for Greengrass nucleus version 2.12.5 release.  | 
|  2.12.4  |  Version updated for Greengrass nucleus version 2.12.4 release.  | 
|  2.12.3  |   This version is no longer available. The improvements in this version are available in later versions of this component.  Version updated for Greengrass nucleus version 2.12.3 release.  | 
|  2.12.2  |  Version updated for Greengrass nucleus version 2.12.2 release.  | 
|  2.12.1  |  Version updated for Greengrass nucleus version 2.12.1 release.  | 
|  2.12.0  |  Version updated for Greengrass nucleus version 2.12.0 release.  | 
|  2.11.3  |  Version updated for Greengrass nucleus version 2.11.3 release.  | 
|  2.11.2  |  Version updated for Greengrass nucleus version 2.11.2 release.  | 
|  2.11.1  |  Version updated for Greengrass nucleus version 2.11.1 release.  | 
|  2.11.0  |  <a name="changelog-cli-2.11.0"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-cli-component.html)  | 
|  2.10.3  |  Version updated for Greengrass nucleus version 2.10.3 release.  | 
|  2.10.2  |  Version updated for Greengrass nucleus version 2.10.2 release.  | 
|  2.10.1  |  Version updated for Greengrass nucleus version 2.10.1 release.  | 
|  2.10.0  |  Version updated for Greengrass nucleus version 2.10.0 release.  | 
|  2.9.6  |  Version updated for Greengrass nucleus version 2.9.6 release.  | 
|  2.9.5  |  Version updated for Greengrass nucleus version 2.9.5 release.  | 
|  2.9.4  |  Version updated for Greengrass nucleus version 2.9.4 release.  | 
|  2.9.3  |  Version updated for Greengrass nucleus version 2.9.3 release.  | 
|  2.9.2  |  Version updated for Greengrass nucleus version 2.9.2 release.  | 
|  2.9.1  |  Version updated for Greengrass nucleus version 2.9.1 release.  | 
|  2.9.0  | Version updated for Greengrass nucleus version 2.9.0 release. | 
|  2.8.1  |  Version updated for Greengrass nucleus version 2.8.1 release.  | 
|  2.8.0  | Version updated for Greengrass nucleus version 2.8.0 release. | 
|  2.7.0  |  Version updated for Greengrass nucleus version 2.7.0 release.  | 
|  2.6.0  |  <a name="changelog-greengrass-cli-2.6.0"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-cli-component.html)  | 
|  2.5.6  |  Version updated for Greengrass nucleus version 2.5.6 release.  | 
|  2.5.5  |  Version updated for Greengrass nucleus version 2.5.5 release.  | 
|  2.5.4  |  Version updated for Greengrass nucleus version 2.5.4 release.  | 
|  2.5.3  |  Version updated for Greengrass nucleus version 2.5.3 release.  | 
|  2.5.2  |  Version updated for Greengrass nucleus version 2.5.2 release.  | 
|  2.5.1  |  Version updated for Greengrass nucleus version 2.5.1 release.  | 
|  2.5.0  |  <a name="changelog-greengrass-cli-2.5.0"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-cli-component.html)  | 
|  2.4.0  |  <a name="changelog-greengrass-cli-2.4.0"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-cli-component.html)  | 
|  2.3.0  |  Version updated for Greengrass nucleus version 2.3.0 release.  | 
|  2.2.0  |  Version updated for Greengrass nucleus version 2.2.0 release.  | 
|  2.1.0  |  Version updated for Greengrass nucleus version 2.1.0 release.  | 
|  2.0.5  | Version updated for Greengrass nucleus version 2.0.5 release. | 
|  2.0.4  | Version updated for Greengrass nucleus version 2.0.4 release. | 
|  2.0.3  |  Initial version.  | 

# IP detector
IP detector v2.2.1 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/ip-detector-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/ip-detector-component.html)

IP detector component v2.2.1 is available.IP detector v2.2.0 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/ip-detector-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/ip-detector-component.html)

IP detector component v2.2.0 is available. This release adds support for IPv6. You can now use IPv6 for local messaging.IP detector v2.1.9 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/ip-detector-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/ip-detector-component.html)

IP detector component v2.1.9 is available. This release adjusts the IP acquired step to only send logs at the debug log level.

The IP detector component (`aws.greengrass.clientdevices.IPDetector`) does the following:
+ Monitors the Greengrass core device's network connectivity information. This information includes the core device's network endpoints and the port where an MQTT broker operates.
+ Updates the core device's connectivity information in the AWS IoT Greengrass cloud service.

Client devices can use Greengrass cloud discovery to retrieve associated core devices' connectivity information. Then, client devices can try to connect to each core device until they successfully connect.

**Note**  <a name="client-device-component-context"></a>
Client devices are local IoT devices that connect to a Greengrass core device to send MQTT messages and data to process. For more information, see [Interact with local IoT devices](interact-with-local-iot-devices.md).

The IP detector component replaces a core device's existing connectivity information with the information it detects. Because this component removes existing information, you can either use the IP detector component, or manually manage connectivity information.

**Topics**
+ [

## Versions
](#ip-detector-component-versions)
+ [

## Type
](#ip-detector-component-type)
+ [

## Operating system
](#ip-detector-component-os-support)
+ [

## Requirements
](#ip-detector-component-requirements)
+ [

## Dependencies
](#ip-detector-component-dependencies)
+ [

## Configuration
](#ip-detector-component-configuration)
+ [

## Local log file
](#ip-detector-component-log-file)
+ [

## Changelog
](#ip-detector-component-changelog)

## Versions


This component has the following versions:
+ 2.2.x
+ 2.1.x
+ 2.0.x

## Type


<a name="public-component-type-plugin-para1"></a>This component is a plugin component (`aws.greengrass.plugin`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs this component in the same Java Virtual Machine (JVM) as the nucleus. The nucleus restarts when you change this component's version on the core device.

<a name="public-component-type-plugin-para2"></a>This component uses the same log file as the Greengrass nucleus. For more information, see [Monitor AWS IoT Greengrass logs](monitor-logs.md).

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on core devices that run the following operating systems:
+ Linux
+ Windows

## Requirements


This component has the following requirements:
+ The [Greengrass service role](greengrass-service-role.md) must be associated to your AWS account and allow the `iot:GetThingShadow` and `iot:UpdateThingShadow` permissions.
+ The core device's AWS IoT policy must allow the `greengrass:UpdateConnectivityInfo` permission. For more information, see [AWS IoT policies for data plane operations](device-auth.md#iot-policies) and [Minimal AWS IoT policy to support client devices](device-auth.md#client-device-support-minimal-iot-policy).
+ If you configure the core device's MQTT broker component to use a port other than the default port 8883, you must use IP detector v2.1.0 or later. Configure it to report the port where the broker operates.
+ If you have a complex network setup, the IP detector component might not be able to identify the endpoints where client devices can connect to the core device. If the IP detector component can't manage the endpoints, you must manually manage the core device endpoints instead. For example, if the core device is behind a router that forwards the MQTT broker port to it, you must specify the router's IP address as an endpoint for the core device. For more information, see [Manage core device endpoints](manage-core-device-endpoints.md).
+ The IP detector component is supported to run in a VPC.

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#ip-detector-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

------
#### [ 2.2.3 ]

The following table lists the dependencies for version 2.2.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.2.0 <2.17.0 | Soft | 

------
#### [ 2.2.2 ]

The following table lists the dependencies for version 2.2.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.2.0 <2.16.0 | Soft | 

------
#### [ 2.2.1 ]

The following table lists the dependencies for version 2.2.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.2.0 <2.15.0 | Soft | 

------
#### [ 2.2.0 ]

The following table lists the dependencies for version 2.2.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.2.0 <2.14.0 | Soft | 

------
#### [ 2.1.8 – 2.1.9 ]

The following table lists the dependencies for versions 2.1.8 and 2.1.9 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.2.0 <2.13.0 | Soft | 

------
#### [ 2.1.7 ]

The following table lists the dependencies for version 2.1.7 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.2.0 <2.12.0 | Soft | 

------
#### [ 2.1.6 ]

The following table lists the dependencies for version 2.1.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.2.0 <2.11.0 | Soft | 

------
#### [ 2.1.5 ]

The following table lists the dependencies for version 2.1.5 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.2.0 <2.10.0 | Soft | 

------
#### [ 2.1.4 ]

The following table lists the dependencies for version 2.1.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.2.0 <2.9.0 | Soft | 

------
#### [ 2.1.3 ]

The following table lists the dependencies for version 2.1.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.2.0 <2.8.0 | Soft | 

------
#### [ 2.1.2 ]

The following table lists the dependencies for version 2.1.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.2.0 <2.7.0 | Soft | 

------
#### [ 2.1.1 ]

The following table lists the dependencies for version 2.1.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.2.0 <2.6.0 | Soft | 

------
#### [ 2.1.0 and 2.0.2 ]

The following table lists the dependencies for versions 2.1.0 and 2.0.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.2.0 <2.5.0 | Soft | 

------
#### [ 2.0.1 ]

The following table lists the dependencies for version 2.0.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.2.0 <2.4.0 | Soft | 

------
#### [ 2.0.0 ]

The following table lists the dependencies for version 2.0.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.2.0 <2.3.0 | Soft | 

------

For more information about component dependencies, see the [component recipe reference](component-recipe-reference.md#recipe-reference-component-dependencies).

## Configuration


This component provides the following configuration parameters that you can customize when you deploy the component.

------
#### [ 2.2.x ]

`defaultPort`  <a name="ip-detector-component-configuration-default-port"></a>
<a name="ip-detector-component-configuration-default-port-definition"></a>(Optional) The MQTT broker port to report when this component detects IP addresses. You must specify this parameter if you configure the MQTT broker to use a different port than the default port 8883.  
Default: `8883`

`includeIPv4LoopbackAddrs`  <a name="ip-detector-component-configuration-include-ipv4-loopback-addrs"></a>
<a name="ip-detector-component-configuration-include-ipv4-loopback-addrs-definition"></a>(Optional) You can enable this option to detect and report IPv4 loopback addresses. These are IP addresses, such as `localhost`, where a device can communicate with itself. Use this option in test environments where the core device and client device run on the same system.  
Default: `false`

`includeIPv4LinkLocalAddrs`  <a name="ip-detector-component-configuration-include-ipv4-link-local-addrs"></a>
<a name="ip-detector-component-configuration-include-ipv4-link-local-addrs-definition"></a>(Optional) You can enable this option to detect and report IPv4 [link-local addresses](https://en.wikipedia.org/wiki/Link-local_address). Use this option if the core device's network doesn't have Dynamic Host Configuration Protocol (DHCP) or statically assigned IP addresses.  
Default: `false`

`includeIPv6LoopbackAddrs`  <a name="ip-detector-component-configuration-include-ipv6-loopback-addrs"></a>
<a name="ip-detector-component-configuration-include-ipv6-loopback-addrs-definition"></a>(Optional) You can enable this option to detect and report IPv6 loopback addresses. These are IP addresses, such as `localhost`, where a device can communicate with itself. Use this option in test environments where the core device and client device run on the same system. You must set `includeIPv4Addrs` to `false` and `includeIPv6Addrs` to `true` to use this option.  
Default: `false`

`includeIPv6LinkLocalAddrs`  <a name="ip-detector-component-configuration-include-ipv6-link-local-addrs"></a>
<a name="ip-detector-component-configuration-include-ipv6-link-local-addrs-definition"></a>(Optional) You can enable this option to detect and report IPv6 [link-local addresses](https://en.wikipedia.org/wiki/Link-local_address). Use this option if the core device's network doesn't have Dynamic Host Configuration Protocol (DHCP) or statically assigned IP addresses. You must set `includeIPv4Addrs` to `false` and `includeIPv6Addrs` to `true` to use this option.  
Default: `false`

`includeIPv4Addrs`  <a name="ip-detector-component-configuration-include-ipv4-addrs"></a>
<a name="ip-detector-component-configuration-include-ipv4-addrs-definition"></a>(Optional) The default is set to `true`. You can enable this option to publish IPv4 addresses found on the core device.  
Default: `true`

`includeIPv6Addrs`  <a name="ip-detector-component-configuration-include-ipv6-addrs"></a>
<a name="ip-detector-component-configuration-include-ipv6-addrs-definition"></a>(Optional) You can enable this option to publish IPv6 addresses found on the core device. Set `includeIPv4Addrs` to `false` to use this option.  
Default: `false`

------
#### [ 2.1.x ]

`defaultPort`  <a name="ip-detector-component-configuration-default-port"></a>
<a name="ip-detector-component-configuration-default-port-definition"></a>(Optional) The MQTT broker port to report when this component detects IP addresses. You must specify this parameter if you configure the MQTT broker to use a different port than the default port 8883.  
Default: `8883`

`includeIPv4LoopbackAddrs`  <a name="ip-detector-component-configuration-include-ipv4-loopback-addrs"></a>
<a name="ip-detector-component-configuration-include-ipv4-loopback-addrs-definition"></a>(Optional) You can enable this option to detect and report IPv4 loopback addresses. These are IP addresses, such as `localhost`, where a device can communicate with itself. Use this option in test environments where the core device and client device run on the same system.  
Default: `false`

`includeIPv4LinkLocalAddrs`  <a name="ip-detector-component-configuration-include-ipv4-link-local-addrs"></a>
<a name="ip-detector-component-configuration-include-ipv4-link-local-addrs-definition"></a>(Optional) You can enable this option to detect and report IPv4 [link-local addresses](https://en.wikipedia.org/wiki/Link-local_address). Use this option if the core device's network doesn't have Dynamic Host Configuration Protocol (DHCP) or statically assigned IP addresses.  
Default: `false`

------
#### [ 2.0.x ]

`includeIPv4LoopbackAddrs`  <a name="ip-detector-component-configuration-include-ipv4-loopback-addrs"></a>
<a name="ip-detector-component-configuration-include-ipv4-loopback-addrs-definition"></a>(Optional) You can enable this option to detect and report IPv4 loopback addresses. These are IP addresses, such as `localhost`, where a device can communicate with itself. Use this option in test environments where the core device and client device run on the same system.  
Default: `false`

`includeIPv4LinkLocalAddrs`  <a name="ip-detector-component-configuration-include-ipv4-link-local-addrs"></a>
<a name="ip-detector-component-configuration-include-ipv4-link-local-addrs-definition"></a>(Optional) You can enable this option to detect and report IPv4 [link-local addresses](https://en.wikipedia.org/wiki/Link-local_address). Use this option if the core device's network doesn't have Dynamic Host Configuration Protocol (DHCP) or statically assigned IP addresses.  
Default: `false`

------

## Local log file


This component uses the same log file as the [Greengrass nucleus](greengrass-nucleus-component.md) component.

------
#### [ Linux ]

```
/greengrass/v2/logs/greengrass.log
```

------
#### [ Windows ]

```
C:\greengrass\v2\logs\greengrass.log
```

------

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the path to the AWS IoT Greengrass root folder.

------
#### [ Linux ]

  ```
  sudo tail -f /greengrass/v2/logs/greengrass.log
  ```

------
#### [ Windows (PowerShell) ]

  ```
  Get-Content C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
  ```

------

## Changelog


The following table describes the changes in each version of the component.


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.2.3  |  Version updated for Greengrass nucleus version 2.16.0 release.  | 
|  2.2.2  | Version updated for Greengrass nucleus version 2.15.0 release. | 
|  2.2.1  | Version updated for Greengrass nucleus version 2.14.0 release. | 
|  2.2.0  | Version updated for Greengrass nucleus version 2.13.0 release. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/ip-detector-component.html)  | 
|  2.1.9  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/ip-detector-component.html)  | 
|  2.1.8  | Version updated for Greengrass nucleus version 2.12.0 release. | 
|  2.1.7  | Version updated for Greengrass nucleus version 2.11.0 release. | 
|  2.1.6  | Version updated for Greengrass nucleus version 2.10.0 release. | 
|  2.1.5  | Version updated for Greengrass nucleus version 2.9.0 release. | 
|  2.1.4  | Version updated for Greengrass nucleus version 2.8.0 release. | 
|  2.1.3  |  Version updated for Greengrass nucleus version 2.7.0 release.  | 
|  2.1.2  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/ip-detector-component.html)  | 
|  2.1.1  |  Version updated for Greengrass nucleus version 2.5.0 release.  | 
|  2.1.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/ip-detector-component.html)  | 
|  2.0.2  |  Version updated for Greengrass nucleus version 2.4.0 release.  | 
|  2.0.1  |  Version updated for Greengrass nucleus version 2.3.0 release.  | 
|  2.0.0  |  Initial version.  | 

# Firehose


The Firehose component (`aws.greengrass.KinesisFirehose`) publishes data through Amazon Data Firehose delivery streams to destinations, such as Amazon S3, Amazon Redshift, and Amazon OpenSearch Service. For more information, see [What is Amazon Data Firehose?](https://docs.aws.amazon.com/firehose/latest/dev/what-is-this-service.html) in the *Amazon Data Firehose Developer Guide*.

To publish to a Kinesis delivery stream with this component, publish a message to a topic where this component subscribes. By default, this component subscribes to the `kinesisfirehose/message` and `kinesisfirehose/message/binary/#` [local publish/subscribe](ipc-publish-subscribe.md) topics. You can specify other topics, including AWS IoT Core MQTT topics, when you deploy this component.

**Note**  
This component provides similar functionality to the Firehose connector in AWS IoT Greengrass V1. For more information, see [Firehose connector](https://docs.aws.amazon.com/greengrass/latest/developerguide/kinesis-firehose-connector.html) in the *AWS IoT Greengrass V1 Developer Guide*.

**Topics**
+ [

## Versions
](#kinesis-firehose-component-versions)
+ [

## Type
](#kinesis-firehose-component-type)
+ [

## Operating system
](#kinesis-firehose-component-os-support)
+ [

## Requirements
](#kinesis-firehose-component-requirements)
+ [

## Dependencies
](#kinesis-firehose-component-dependencies)
+ [

## Configuration
](#kinesis-firehose-component-configuration)
+ [

## Input data
](#kinesis-firehose-component-input-data)
+ [

## Output data
](#kinesis-firehose-component-output-data)
+ [

## Local log file
](#kinesis-firehose-component-log-file)
+ [

## Licenses
](#kinesis-firehose-component-licenses)
+ [

## Changelog
](#kinesis-firehose-component-changelog)
+ [

## See also
](#kinesis-firehose-component-see-also)

## Versions


This component has the following versions:
+ 2.1.x
+ 2.0.x

## Type


<a name="public-component-type-lambda"></a>This <a name="public-component-type-lambda-phrase"></a>component is a Lambda component (`aws.greengrass.lambda`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs this component's Lambda function using the [Lambda launcher component](lambda-launcher-component.md).

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on Linux core devices only.

## Requirements


This component has the following requirements:
+ <a name="core-device-lambda-function-requirements"></a>Your core device must meet the requirements to run Lambda functions. If you want the core device to run containerized Lambda functions, the device must meet the requirements to do so. For more information, see [Lambda function requirements](setting-up.md#greengrass-v2-lambda-requirements).
+ <a name="public-component-python3-requirement"></a>[Python](https://www.python.org/) version 3.7 installed on the core device and added to the PATH environment variable.
+ The [Greengrass device role](device-service-role.md) must allow the `firehose:PutRecord` and `firehose:PutRecordBatch` actions, as shown in the following example IAM policy.

------
#### [ JSON ]

****  

  ```
  {
    "Version":"2012-10-17",		 	 	 
    "Statement": [
      {
        "Action": [
          "firehose:PutRecord",
          "firehose:PutRecordBatch"
        ],
        "Effect": "Allow",
        "Resource": [
          "arn:aws:firehose:us-east-1:123456789012:deliverystream/stream-name"
        ]
      }
    ]
  }
  ```

------

  You can dynamically override the default delivery stream in the input message payload for this component. If your application uses this feature, the IAM policy must include all target streams as resources. You can grant granular or conditional access to resources (for example, by using a wildcard `*` naming scheme).
+ <a name="connector-component-legacy-subscription-router-dependency"></a>To receive output data from this component, you must merge the following configuration update for the [legacy subscription router component](legacy-subscription-router-component.md) (`aws.greengrass.LegacySubscriptionRouter`) when you deploy this component. This configuration specifies the topic where this component publishes responses.

------
#### [ Legacy subscription router v2.1.x ]

  ```
  {
    "subscriptions": {
      "aws-greengrass-kinesisfirehose": {
        "id": "aws-greengrass-kinesisfirehose",
        "source": "component:aws.greengrass.KinesisFirehose",
        "subject": "kinesisfirehose/message/status",
        "target": "cloud"
      }
    }
  }
  ```

------
#### [ Legacy subscription router v2.0.x ]

  ```
  {
    "subscriptions": {
      "aws-greengrass-kinesisfirehose": {
        "id": "aws-greengrass-kinesisfirehose",
        "source": "arn:aws:lambda:region:aws:function:aws-greengrass-kinesisfirehose:version",
        "subject": "kinesisfirehose/message/status",
        "target": "cloud"
      }
    }
  }
  ```<a name="connector-component-legacy-subscription-router-dependency-replace"></a>
  + Replace *region* with the AWS Region that you use.
  + Replace *version* with the version of the Lambda function that this component runs. To find the Lambda function version, you must view the recipe for the version of this component that you want to deploy. Open this component's details page in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass), and look for the **Lambda function** key-value pair. This key-value pair contains the name and version of the Lambda function.

**Important**  <a name="connector-component-legacy-subscription-router-dependency-note"></a>
You must update the Lambda function version on the legacy subscription router every time you deploy this component. This ensures that you use the correct Lambda function version for the component version that you deploy.

------

  <a name="connector-component-create-deployments"></a>For more information, see [Create deployments](create-deployments.md).
+ The Firehose component is supported to run in a VPC. To deploy this component in a VPC, the following is required.
  + The Firehose component must have connectivity to `firehose.region.amazonaws.com` which has the VPC endpoint of `com.amazonaws.region.kinesis-firehose`.

### Endpoints and ports


This component must be able to perform outbound requests to the following endpoints and ports, in addition to endpoints and ports required for basic operation. For more information, see [Allow device traffic through a proxy or firewall](allow-device-traffic.md).


| Endpoint | Port | Required | Description | 
| --- | --- | --- | --- | 
|  `firehose.region.amazonaws.com`  | 443 | Yes |  Upload data to Firehose.  | 

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#kinesis-firehose-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

------
#### [ 2.1.10 ]

The following table lists the dependencies for version 2.1.10 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.16.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.1.9 ]

The following table lists the dependencies for version 2.1.9 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.15.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.1.8 ]

The following table lists the dependencies for version 2.1.8 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.14.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.1.7 ]

The following table lists the dependencies for version 2.1.7 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.13.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.1.6 ]

The following table lists the dependencies for version 2.1.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.12.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.1.5 ]

The following table lists the dependencies for version 2.1.5 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.11.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.1.4 ]

The following table lists the dependencies for version 2.1.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.10.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.1.3 ]

The following table lists the dependencies for version 2.1.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.9.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.1.2 ]

The following table lists the dependencies for version 2.1.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.8.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.1.1 ]

The following table lists the dependencies for version 2.1.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.7.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.0.8 - 2.1.0 ]

The following table lists the dependencies for versions 2.0.8 and 2.1.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.6.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.0.7 ]

The following table lists the dependencies for version 2.0.7 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.5.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.0.6 ]

The following table lists the dependencies for version 2.0.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.4.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.0.5 ]

The following table lists the dependencies for version 2.0.5 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.3.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.0.4 ]

The following table lists the dependencies for version 2.0.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.2.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.0.3 ]

The following table lists the dependencies for version 2.0.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.3 <2.1.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | >=1.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | >=1.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | >=1.0.0  | Hard | 

------

For more information about component dependencies, see the [component recipe reference](component-recipe-reference.md#recipe-reference-component-dependencies).

## Configuration


This component provides the following configuration parameters that you can customize when you deploy the component.

**Note**  <a name="connector-component-lambda-parameters"></a>
This component's default configuration includes Lambda function parameters. We recommend that you edit only the following parameters to configure this component on your devices.

`lambdaParams`  
An object that contains the parameters for this component's Lambda function. This object contains the following information:    
`EnvironmentVariables`  
An object that contains the Lambda function's parameters. This object contains the following information:    
`DEFAULT_DELIVERY_STREAM_ARN`  
The ARN of the default Firehose delivery stream where the component sends data. You can override the destination stream with the `delivery_stream_arn` property in the input message payload.  
The core device role must allow the required actions on all target delivery streams. For more information, see [Requirements](#kinesis-firehose-component-requirements).  
`PUBLISH_INTERVAL`  
(Optional) The maximum number of seconds to wait before the component publishes batched data to Firehose. To configure the component to publish metrics as it receives them, which means without batching, specify `0`.  
This value can be at most 900 seconds.  
Default: 10 seconds  
`DELIVERY_STREAM_QUEUE_SIZE`  
(Optional) The maximum number of records to retain in memory before the component rejects new records for the same delivery stream.  
This value must be at least 2,000 records.  
Default: 5,000 records

`containerMode`  <a name="connector-component-container-mode-parameter"></a>
(Optional) The containerization mode for this component. Choose from the following options:  <a name="lambda-function-component-container-mode-parameter"></a>
+ `NoContainer` – The component doesn't run in an isolated runtime environment.
+ `GreengrassContainer` – The component runs in an isolated runtime environment inside the AWS IoT Greengrass container.
Default: `GreengrassContainer`

`containerParams`  
<a name="connector-component-container-params-description"></a>(Optional) An object that contains the container parameters for this component. The component uses these parameters if you specify `GreengrassContainer` for `containerMode`.  
This object contains the following information:    
`memorySize`  
<a name="connector-component-container-params-memory-size-description"></a>(Optional) The amount of memory (in kilobytes) to allocate to the component.  
Defaults to 64 MB (65,535 KB).

`pubsubTopics`  <a name="connector-component-pubsub-topics-parameter"></a>
(Optional) An object that contains the topics where the component subscribes to receive messages. You can specify each topic and whether the component subscribes to MQTT topics from AWS IoT Core or local publish/subscribe topics.  
This object contains the following information:    
`0` – This is an array index as a string.  
An object that contains the following information:    
`type`  
(Optional) The type of publish/subscribe messaging that this component uses to subscribe to messages. Choose from the following options:  
+ `PUB_SUB` – Subscribe to local publish/subscribe messages. If you choose this option, the topic can't contain MQTT wildcards. For more information about how to send messages from custom component when you specify this option, see [Publish/subscribe local messages](ipc-publish-subscribe.md).
+ `IOT_CORE` – Subscribe to AWS IoT Core MQTT messages. If you choose this option, the topic can contain MQTT wildcards. For more information about how to send messages from custom components when you specify this option, see [Publish/subscribe AWS IoT Core MQTT messages](ipc-iot-core-mqtt.md).
Default: `PUB_SUB`  
`topic`  
(Optional) The topic to which the component subscribes to receive messages. If you specify `IotCore` for `type`, you can use MQTT wildcards (`+` and `#`) in this topic.

**Example: Configuration merge update (container mode)**  

```
{
  "lambdaExecutionParameters": {
    "EnvironmentVariables": {
      "DEFAULT_DELIVERY_STREAM_ARN": "arn:aws:firehose:us-west-2:123456789012:deliverystream/mystream"
    }
  },
  "containerMode": "GreengrassContainer"
}
```

**Example: Configuration merge update (no container mode)**  

```
{
  "lambdaExecutionParameters": {
    "EnvironmentVariables": {
      "DEFAULT_DELIVERY_STREAM_ARN": "arn:aws:firehose:us-west-2:123456789012:deliverystream/mystream"
    }
  },
  "containerMode": "NoContainer"
}
```

## Input data


This component accepts stream content on the following topics and sends the content to the target delivery stream. The component accepts two types of input data:
+ JSON data on the `kinesisfirehose/message` topic.
+ Binary data on the `kinesisfirehose/message/binary/#` topic.

**Default topic for JSON data (local publish/subscribe):** `kinesisfirehose/message`  
<a name="connector-component-input-properties"></a>The message accepts the following properties. Input messages must be in JSON format.    
`request`  
The data to send to the delivery stream and the target delivery stream, if different from the default stream.  
Type: `object` that contains the following information:    
`data`  
The data to send to the delivery stream.  
Type: `string`  
`delivery_stream_arn`  
(Optional) The ARN of the target Firehose delivery stream. Specify this property to override the default delivery stream.  
Type: `string`  
`id`  <a name="connector-component-input-property-id"></a>
An arbitrary ID for the request. Use this property to map an input request to an output response. When you specify this property, the component sets the `id` property in the response object to this value.  
Type: `string`

**Example input**  

```
{
  "request": {
    "delivery_stream_arn": "arn:aws:firehose:region:account-id:deliverystream/stream2-name",
    "data": "Data to send to the delivery stream."
  },
  "id": "request123"
}
```

**Default topic for binary data (local publish/subscribe):** `kinesisfirehose/message/binary/#`  
Use this topic to send a message that contains binary data. The component doesn't parse binary data. The component streams the data as is.  
To map the input request to an output response, replace the `#` wildcard in the message topic with an arbitrary request ID. For example, if you publish a message to `kinesisfirehose/message/binary/request123`, the `id` property in the response object is set to `request123`.  
If you don't want to map a request to a response, you can publish your messages to `kinesisfirehose/message/binary/`. Be sure to include the trailing slash (`/`).

## Output data


 <a name="connector-component-output-data"></a>This component publishes responses as output data on the following MQTT topic by default. You must specify this topic as the `subject` in the configuration for the [legacy subscription router component](legacy-subscription-router-component.md). For more information about how to subscribe to messages on this topic in your custom components, see [Publish/subscribe AWS IoT Core MQTT messages](ipc-iot-core-mqtt.md). 

**Default topic (AWS IoT Core MQTT):** `kinesisfirehose/message/status`

**Example output**  
The response contains the status of each data record sent in the batch.  

```
{
  "response": [
    {
      "ErrorCode": "error",
      "ErrorMessage": "test error",
      "id": "request123",
      "status": "fail"
    },
    {
      "firehose_record_id": "xyz2",
      "id": "request456",
      "status": "success"
    },
    {
      "firehose_record_id": "xyz3",
      "id": "request890",
      "status": "success"
    }
  ]
}
```

**Note**  <a name="connector-component-retryable-error"></a>
If the component detects an error that can be retried, such as a connection error, it retries the publish in the next batch.

## Local log file


This component uses the following log file.

```
/greengrass/v2/logs/aws.greengrass.KinesisFirehose.log
```

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` with the path to the AWS IoT Greengrass root folder.

  ```
  sudo tail -f /greengrass/v2/logs/aws.greengrass.KinesisFirehose.log
  ```

## Licenses


This component includes the following third-party software/licensing:<a name="boto-3-licenses"></a>
+ [AWS SDK for Python (Boto3)](https://pypi.org/project/boto3/)/Apache License 2.0
+ [botocore](https://pypi.org/project/botocore/)/Apache License 2.0
+ [dateutil](https://pypi.org/project/python-dateutil/1.4/)/PSF License
+ [docutils](https://pypi.org/project/docutils/)/BSD License, GNU General Public License (GPL), Python Software Foundation License, Public Domain
+ [jmespath](https://pypi.org/project/jmespath/)/MIT License
+ [s3transfer](https://pypi.org/project/s3transfer/)/Apache License 2.0
+ [urllib3](https://pypi.org/project/urllib3/)/MIT License

<a name="component-core-software-license"></a>This component is released under the [Greengrass Core Software License Agreement](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf).

## Changelog


The following table describes the changes in each version of the component.


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.1.10  | Version updated for Greengrass nucleus version 2.15.0 release. | 
|  2.1.9  | Version updated for Greengrass nucleus version 2.14.0 release. | 
|  2.1.8  | Version updated for Greengrass nucleus version 2.13.0 release. | 
|  2.1.7  | Version updated for Greengrass nucleus version 2.12.0 release. | 
|  2.1.6  | Version updated for Greengrass nucleus version 2.11.0 release. | 
|  2.1.5  | Version updated for Greengrass nucleus version 2.10.0 release. | 
|  2.1.4  | Version updated for Greengrass nucleus version 2.9.0 release. | 
|  2.1.3  | Version updated for Greengrass nucleus version 2.8.0 release. | 
|  2.1.2  |  Version updated for Greengrass nucleus version 2.7.0 release.  | 
|  2.1.1  |  Version updated for Greengrass nucleus version 2.6.0 release.  | 
|  2.1.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/kinesis-firehose-component.html)  | 
|  2.0.8  |  Version updated for Greengrass nucleus version 2.5.0 release.  | 
|  2.0.7  |  Version updated for Greengrass nucleus version 2.4.0 release.  | 
|  2.0.6  |  Version updated for Greengrass nucleus version 2.3.0 release.  | 
|  2.0.5  |  Version updated for Greengrass nucleus version 2.2.0 release.  | 
|  2.0.4  |  Version updated for Greengrass nucleus version 2.1.0 release.  | 
|  2.0.3  |  Initial version.  | 

## See also

+ [What is Amazon Data Firehose?](https://docs.aws.amazon.com/firehose/latest/dev/what-is-this-service.html) in the *Amazon Data Firehose Developer Guide*

# Lambda launcher
Lambda launcher v2.0.13 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/lambda-launcher-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/lambda-launcher-component.html)

Version 2.0.13 of the Lambda launcher component is available. This release includes general bug fixes and improvements.Lambda launcher v2.0.12 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/lambda-launcher-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/lambda-launcher-component.html)

Version 2.0.12 of the Lambda launcher component is available. This release fixes an issue where the Lambda launcher could throw an error if the previous process was not stopped properly.Lambda launcher v2.0.11 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/lambda-launcher-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/lambda-launcher-component.html)

Version 2.0.11 of the Lambda launcher component is available. This version supports Lambda Manager 2.3.0.Lambda launcher v2.0.6 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/lambda-launcher-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/lambda-launcher-component.html)

Version 2.0.6 of the Lambda launcher component is available. This version includes performance improvements and bug fixes.

The Lambda launcher component (`aws.greengrass.LambdaLauncher`) starts and stops AWS Lambda functions on AWS IoT Greengrass core devices. This component also sets up any containerization and runs processes as the users that you specify.

**Note**  <a name="lambda-component-dependency-note"></a>
When you deploy a Lambda function component to a core device, the deployment also includes this component. For more information, see [Run AWS Lambda functions](run-lambda-functions.md).

**Topics**
+ [

## Versions
](#lambda-launcher-component-versions)
+ [

## Type
](#lambda-launcher-component-type)
+ [

## Operating system
](#lambda-launcher-component-os-support)
+ [

## Requirements
](#lambda-launcher-component-requirements)
+ [

## Dependencies
](#lambda-launcher-component-dependencies)
+ [

## Configuration
](#lambda-launcher-component-configuration)
+ [

## Local log file
](#lambda-launcher-component-log-file)
+ [

## Changelog
](#lambda-launcher-component-changelog)

## Versions


This component has the following versions:
+ 2.0.x

## Type


<a name="public-component-type-generic"></a>This <a name="public-component-type-generic-phrase"></a>component is a generic component (`aws.greengrass.generic`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs the component's lifecycle scripts.

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on Linux core devices only.

## Requirements


This component has the following requirements:
+ <a name="core-device-lambda-function-requirements"></a>Your core device must meet the requirements to run Lambda functions. If you want the core device to run containerized Lambda functions, the device must meet the requirements to do so. For more information, see [Lambda function requirements](setting-up.md#greengrass-v2-lambda-requirements).
+ The Lambda launcher component is supported to run in a VPC.

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#lambda-launcher-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

------
#### [ 2.0.11 – 2.0.13 ]

The following table lists the dependencies for versions 2.0.11 to 2.0.13 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Lambda manager](lambda-manager-component.md) | >=2.0.0 <2.4.0  | Hard | 

------
#### [ 2.0.9 – 2.0.10 ]

The following table lists the dependencies for versions 2.0.9 to 2.0.10 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Lambda manager](lambda-manager-component.md) | >=2.0.0 <2.3.0  | Hard | 

------
#### [ 2.0.4 - 2.0.8 ]

The following table lists the dependencies for versions 2.0.4 to 2.0.8 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Lambda manager](lambda-manager-component.md) | >=2.0.0 <2.2.0  | Hard | 

------
#### [ 2.0.3 ]

The following table lists the dependencies for version 2.0.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Lambda manager](lambda-manager-component.md) | >=2.0.3 <2.1.0 | Hard | 

------

For more information about component dependencies, see the [component recipe reference](component-recipe-reference.md#recipe-reference-component-dependencies).

## Configuration


This component doesn't have any configuration parameters.

## Local log file


This component uses the following log file.

```
/greengrass/v2/logs/lambdaFunctionComponentName.log
```

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` with the path to the AWS IoT Greengrass root folder, and replace *lambdaFunctionComponentName* with the name of the Lambda function component that this component launches.

  ```
  sudo tail -f /greengrass/v2/logs/lambdaFunctionComponentName.log
  ```

## Changelog


The following table describes the changes in each version of the component.


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.0.13  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/lambda-launcher-component.html)  | 
|  2.0.12  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/lambda-launcher-component.html)  | 
|  2.0.11  |  Support for Lambda manager 2.3.0.  | 
|  2.0.10  |  <a name="changelog-lambda-launcher-2.0.10"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/lambda-launcher-component.html)  | 
|  2.0.9  |  Version updated for Greengrass nucleus version 2.5.0 release.  | 
|  2.0.8  |  Version updated for Greengrass nucleus version 2.4.0 release.  | 
|  2.0.7  |  Version updated for Greengrass nucleus version 2.3.0 release.  | 
|  2.0.6  |  General performance improvements and bug fixes.  | 
|  2.0.4  |  <a name="changelog-lambda-launcher-2.0.4"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/lambda-launcher-component.html)  | 
|  2.0.3  |  Initial version.  | 

# Lambda manager
Lambda manager v2.3.5 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/lambda-manager-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/lambda-manager-component.html)

Lambda manager component v2.3.5 is available.Lambda manager v2.3.4 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/lambda-manager-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/lambda-manager-component.html)

Lambda manager component v2.3.4 is available.Lambda manager v2.3.3 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/lambda-manager-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/lambda-manager-component.html)

Lambda manager component v2.3.3 is available. This version includes general bug fixes and improvements.Lambda manager v2.3.1 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/lambda-manager-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/lambda-manager-component.html)

Lambda manager component v2.3.1 is available.Lambda manager v2.3.0 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/lambda-manager-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/lambda-manager-component.html)

Lambda manager component v2.3.0 is available.Lambda manager v2.1.4 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/lambda-manager-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/lambda-manager-component.html)

Lambda manager component v2.1.4 is available. This release fixes an issue that caused Lambda functions that use NodeJS runtimes to process only one message.

The Lambda manager component (`aws.greengrass.LambdaManager`) manages work items and interprocess communication for AWS Lambda functions that run on the Greengrass core device.

**Note**  <a name="lambda-component-dependency-note"></a>
When you deploy a Lambda function component to a core device, the deployment also includes this component. For more information, see [Run AWS Lambda functions](run-lambda-functions.md).

**Topics**
+ [

## Versions
](#lambda-manager-component-versions)
+ [

## Operating system
](#lambda-manager-component-os-support)
+ [

## Type
](#lambda-manager-component-type)
+ [

## Requirements
](#lambda-manager-component-requirements)
+ [

## Dependencies
](#lambda-manager-component-dependencies)
+ [

## Configuration
](#lambda-manager-component-configuration)
+ [

## Local log file
](#lambda-manager-component-log-file)
+ [

## Changelog
](#lambda-manager-component-changelog)

## Versions


This component has the following versions:
+ 2.3.x
+ 2.2.x
+ 2.1.x
+ 2.0.x

## Operating system


This component can be installed on Linux core devices only.

## Type


<a name="public-component-type-plugin-para1"></a>This component is a plugin component (`aws.greengrass.plugin`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs this component in the same Java Virtual Machine (JVM) as the nucleus. The nucleus restarts when you change this component's version on the core device.

<a name="public-component-type-plugin-para2"></a>This component uses the same log file as the Greengrass nucleus. For more information, see [Monitor AWS IoT Greengrass logs](monitor-logs.md).

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Requirements


This component has the following requirements:
+ <a name="core-device-lambda-function-requirements"></a>Your core device must meet the requirements to run Lambda functions. If you want the core device to run containerized Lambda functions, the device must meet the requirements to do so. For more information, see [Lambda function requirements](setting-up.md#greengrass-v2-lambda-requirements).
+ The Lambda manager component is supported to run in a VPC.

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#lambda-manager-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

------
#### [ 2.3.7 ]

The following table lists the dependencies for version 2.3.7 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.17.0 | Soft | 

------
#### [ 2.3.6 ]

The following table lists the dependencies for version 2.3.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.16.0  | Soft | 

------
#### [ 2.3.5 ]

The following table lists the dependencies for version 2.3.5 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.15.0  | Soft | 

------
#### [ 2.3.4 ]

The following table lists the dependencies for version 2.3.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.14.0  | Soft | 

------
#### [ 2.3.2 and 2.3.3 ]

The following table lists the dependencies for version 2.3.2 and 2.3.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.13.0  | Soft | 

------
#### [ 2.2.10 and 2.3.1 ]

The following table lists the dependencies for version 2.2.10 and 2.3.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.12.0  | Soft | 

------
#### [ 2.2.8 and 2.2.9 ]

The following table lists the dependencies for version 2.2.8 and 2.2.9 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.11.0  | Soft | 

------
#### [ 2.2.7 ]

The following table lists the dependencies for version 2.2.7 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.10.0  | Soft | 

------
#### [ 2.2.6 ]

The following table lists the dependencies for version 2.2.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.9.0  | Soft | 

------
#### [ 2.2.5 ]

The following table lists the dependencies for version 2.2.5 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.8.0  | Soft | 

------
#### [ 2.2.4 ]

The following table lists the dependencies for version 2.2.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.7.0  | Soft | 

------
#### [ 2.2.1 - 2.2.3 ]

The following table lists the dependencies for versions 2.2.1 to 2.2.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.6.0  | Soft | 

------
#### [ 2.2.0 ]

The following table lists the dependencies for version 2.2.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.5.0 <2.6.0  | Soft | 

------
#### [ 2.1.3 and 2.1.4 ]

The following table lists the dependencies for versions 2.1.3 and 2.1.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.5.0  | Soft | 

------
#### [ 2.1.2 ]

The following table lists the dependencies for version 2.1.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.4.0  | Soft | 

------
#### [ 2.1.1 ]

The following table lists the dependencies for version 2.1.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.3.0  | Soft | 

------
#### [ 2.1.0 ]

The following table lists the dependencies for version 2.1.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.2.0  | Soft | 

------
#### [ 2.0.x ]

The following table lists the dependencies for version 2.0.x of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.3 <2.1.0  | Soft | 

------

For more information about component dependencies, see the [component recipe reference](component-recipe-reference.md#recipe-reference-component-dependencies).

## Configuration


This component provides the following configuration parameters that you can customize when you deploy the component.

`logHandlerMode`  
Only for lambda manager versions 2.3.0\$1 
Used to choose the implementation of the Lambda log manager to use. Set the value to `optimized` to use fewer threads to read lambda logs.

`getResultTimeoutInSecond`  
(Optional) The maximum amount of time in seconds that Lambda functions can run before they time out.  
Default: `60`

## Local log file


This component uses the same log file as the [Greengrass nucleus](greengrass-nucleus-component.md) component.

```
/greengrass/v2/logs/greengrass.log
```

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` with the path to the AWS IoT Greengrass root folder.

  ```
  sudo tail -f /greengrass/v2/logs/greengrass.log
  ```

## Changelog


The following table describes the changes in each version of the component.


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.3.7  |  Version updated for Greengrass nucleus version 2.16.0 release.  | 
|  2.3.6  | Version updated for Greengrass nucleus version 2.15.0 release. | 
|  2.3.5  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/lambda-manager-component.html)  | 
|  2.3.4  | Version updated for Greengrass nucleus version 2.13.0 release. | 
|  2.3.3  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/lambda-manager-component.html)  | 
|  2.3.2  | Version updated for Greengrass nucleus version 2.12.0 release. | 
|  2.3.1  |  <a name="changelog-lambda-manager-2.3.1"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/lambda-manager-component.html)  | 
|  2.3.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/lambda-manager-component.html)  | 
|  2.2.11  |  <a name="changelog-lambda-manager-2.2.11"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/lambda-manager-component.html)  | 
|  2.2.10  | Version updated for Greengrass nucleus version 2.11.0 release. | 
|  2.2.9  |  <a name="changelog-lambda-manager-2.2.9"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/lambda-manager-component.html)  | 
|  2.2.8  | Version updated for Greengrass nucleus version 2.10.0 release. | 
|  2.2.7  | Version updated for Greengrass nucleus version 2.9.0 release. | 
|  2.2.6  | Version updated for Greengrass nucleus version 2.8.0 release. | 
|  2.2.5  |  <a name="changelog-lambda-manager-2.2.5"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/lambda-manager-component.html)  | 
|  2.2.4  |  Version updated for Greengrass nucleus version 2.6.0 release.  | 
|  2.2.3  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/lambda-manager-component.html)  | 
|  2.2.2  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/lambda-manager-component.html)  | 
|  2.2.1  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/lambda-manager-component.html)  | 
|  2.2.0  |  <a name="changelog-lambda-manager-2.2.0"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/lambda-manager-component.html)  | 
|  2.1.4  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/lambda-manager-component.html)  | 
|  2.1.3  |  Version updated for Greengrass nucleus version 2.4.0 release.  | 
|  2.1.2  |  Version updated for Greengrass nucleus version 2.3.0 release.  | 
|  2.1.1  |  Version updated for Greengrass nucleus version 2.2.0 release.  | 
|  2.1.0  |  Version updated for Greengrass nucleus version 2.1.0 release.  | 
|  2.0.3  |  Initial version.  | 

# Lambda runtimes


The Lambda runtimes component (`aws.greengrass.LambdaRuntimes`) provides the runtimes that Greengrass core devices use to run AWS Lambda functions.

**Note**  <a name="lambda-component-dependency-note"></a>
When you deploy a Lambda function component to a core device, the deployment also includes this component. For more information, see [Run AWS Lambda functions](run-lambda-functions.md).

**Topics**
+ [

## Versions
](#lambda-runtimes-component-versions)
+ [

## Type
](#lambda-runtimes-component-type)
+ [

## Operating system
](#lambda-runtimes-component-os-support)
+ [

## Requirements
](#lambda-runtimes-component-requirements)
+ [

## Dependencies
](#lambda-runtimes-component-dependencies)
+ [

## Configuration
](#lambda-runtimes-component-configuration)
+ [

## Local log file
](#lambda-runtimes-component-log-file)
+ [

## Changelog
](#lambda-runtimes-component-changelog)

## Versions


This component has the following versions:
+ 2.0.x

## Type


<a name="public-component-type-generic"></a>This <a name="public-component-type-generic-phrase"></a>component is a generic component (`aws.greengrass.generic`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs the component's lifecycle scripts.

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on Linux core devices only.

## Requirements


This component has the following requirements:
+ <a name="core-device-lambda-function-requirements"></a>Your core device must meet the requirements to run Lambda functions. If you want the core device to run containerized Lambda functions, the device must meet the requirements to do so. For more information, see [Lambda function requirements](setting-up.md#greengrass-v2-lambda-requirements).
+ The Lambda runtimes component is supported to run in a VPC.

## Dependencies


This component doesn't have any dependencies.

## Configuration


This component doesn't have any configuration parameters.

## Local log file


This component doesn't output logs.

## Changelog


The following table describes the changes in each version of the component.


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.0.9  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/lambda-runtimes-component.html)  | 
|  2.0.8  |  Version updated for Greengrass nucleus version 2.5.0 release.  | 
|  2.0.7  |  Version updated for Greengrass nucleus version 2.4.0 release.  | 
|  2.0.6  |  Version updated for Greengrass nucleus version 2.3.0 release.  | 
|  2.0.5  |  Version updated for Greengrass nucleus version 2.2.0 release.  | 
|  2.0.4  |  Version updated for Greengrass nucleus version 2.1.0 release.  | 
|  2.0.3  |  Initial version.  | 

# Legacy subscription router


The legacy subscription router (`aws.greengrass.LegacySubscriptionRouter`) manages subscriptions on the Greengrass core device. Subscriptions are a feature of AWS IoT Greengrass V1 that define the topics that Lambda functions can use for MQTT messaging on a core device. For more information, see [Managed subscriptions in the MQTT messaging workflow](https://docs.aws.amazon.com/greengrass/v1/developerguide/gg-sec.html#gg-msg-workflow) in the *AWS IoT Greengrass V1 Developer Guide*.

You can use this component to enable subscriptions for connector components and Lambda function components that use the AWS IoT Greengrass Core SDK.

**Note**  <a name="legacy-subscription-router-requirement-note"></a>
The legacy subscription router component is required only if your Lambda function uses the `publish()` function in the AWS IoT Greengrass Core SDK. If you update your Lambda function code to use the interprocess communication (IPC) interface in the AWS IoT Device SDK V2, you don't need to deploy the legacy subscription router component. For more information, see the following [interprocess communication](interprocess-communication.md) services:  
[Publish/subscribe local messages](ipc-publish-subscribe.md)
[Publish/subscribe AWS IoT Core MQTT messages](ipc-iot-core-mqtt.md)

**Topics**
+ [

## Versions
](#legacy-subscription-router-component-versions)
+ [

## Type
](#legacy-subscription-router-component-type)
+ [

## Operating system
](#legacy-subscription-router-component-os-support)
+ [

## Requirements
](#legacy-subscription-router-component-requirements)
+ [

## Dependencies
](#legacy-subscription-router-component-dependencies)
+ [

## Configuration
](#legacy-subscription-router-component-configuration)
+ [

## Local log file
](#legacy-subscription-router-component-log-file)
+ [

## Changelog
](#legacy-subscription-router-component-changelog)

## Versions


This component has the following versions:
+ 2.1.x
+ 2.0.x

## Type


<a name="public-component-type-generic"></a>This <a name="public-component-type-generic-phrase"></a>component is a generic component (`aws.greengrass.generic`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs the component's lifecycle scripts.

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on Linux core devices only.

## Requirements


This component has the following requirements:
+ The legacy subscription router is supported to run in a VPC.

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#legacy-subscription-router-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

------
#### [ 2.1.15 ]

The following table lists the dependencies for version 2.1.15 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.17.0 | Soft | 

------
#### [ 2.1.14 ]

The following table lists the dependencies for version 2.1.14 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.16.0 | Soft | 

------
#### [ 2.1.13 ]

The following table lists the dependencies for version 2.1.13 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.15.0 | Soft | 

------
#### [ 2.1.12 ]

The following table lists the dependencies for version 2.1.12 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.14.0 | Soft | 

------
#### [ 2.1.11 ]

The following table lists the dependencies for version 2.1.11 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.13.0 | Soft | 

------
#### [ 2.1.10 ]

The following table lists the dependencies for version 2.1.10 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.12.0 | Soft | 

------
#### [ 2.1.9 ]

The following table lists the dependencies for version 2.1.9 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.11.0 | Soft | 

------
#### [ 2.1.8 ]

The following table lists the dependencies for version 2.1.8 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.10.0 | Soft | 

------
#### [ 2.1.7 ]

The following table lists the dependencies for version 2.1.7 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.9.0 | Soft | 

------
#### [ 2.1.6 ]

The following table lists the dependencies for version 2.1.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.8.0 | Soft | 

------
#### [ 2.1.5 ]

The following table lists the dependencies for version 2.1.5 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.7.0 | Soft | 

------
#### [ 2.1.4 ]

The following table lists the dependencies for version 2.1.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.6.0 | Soft | 

------
#### [ 2.1.3 ]

The following table lists the dependencies for version 2.1.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.5.0 | Soft | 

------
#### [ 2.1.2 ]

The following table lists the dependencies for version 2.1.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.4.0 | Soft | 

------
#### [ 2.1.1 ]

The following table lists the dependencies for version 2.1.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.3.0 | Soft | 

------
#### [ 2.1.0 ]

The following table lists the dependencies for version 2.1.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.2.0 | Soft | 

------
#### [ 2.0.3 ]

The following table lists the dependencies for version 2.0.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.3 <2.1.0 | Soft | 

------

For more information about component dependencies, see the [component recipe reference](component-recipe-reference.md#recipe-reference-component-dependencies).

## Configuration


This component provides the following configuration parameters that you can customize when you deploy the component.

------
#### [ v2.1.x ]

`subscriptions`  
<a name="legacy-subscription-router-component-configuration-subscriptions-intro"></a>(Optional) The subscriptions to enable on the core device. This is an object, where each key is a unique ID, and each value is an object that defines the subscription for that connector. You must configure a subscription when you deploy a V1 connector component or a Lambda function that uses the AWS IoT Greengrass Core SDK.  
Each subscription object contains the following information:    
`id`  <a name="legacy-subscription-router-component-configuration-subscription-id"></a>
The unique ID of this subscription. This ID must match the key for this subscription object.  
`source`  
The Lambda function that uses the AWS IoT Greengrass Core SDK to publish MQTT messages on the topics that you specify in `subject`. Specify one of the following:  
+ <a name="legacy-subscription-router-component-configuration-subscription-source-target-component-name"></a>The name of a Lambda function component on the core device. Specify the component name with the `component:` prefix, such as **component:com.example.HelloWorldLambda**.
+ <a name="legacy-subscription-router-component-configuration-subscription-source-target-function-arn"></a>The Amazon Resource Name (ARN) of a Lambda function on the core device.
**Important**  <a name="legacy-subscription-router-function-version-requirement"></a>
If the version of the Lambda function changes, you must configure the subscription with the new version of the function. Otherwise, this component won't route the messages until the version matches the subscription.  
You must specify an Amazon Resource Name (ARN) that includes the version of the function to import. You can't use version aliases like `$LATEST`.
To deploy a subscription for a V1 connector component, specify the name of the component or the ARN of the connector component's Lambda function.  
`subject`  <a name="legacy-subscription-router-component-configuration-subscription-subject"></a>
The MQTT topic or topic filter on which the source and target can publish and receive messages. This value supports the `+` and `#` topic wildcards.  
`target`  
<a name="legacy-subscription-router-component-configuration-subscription-target-intro"></a>The target that receives the MQTT messages on the topics that you specify in `subject`. The subscription specifies that the `source` function publishes MQTT messages to AWS IoT Core or to a Lambda function on the core device. Specify one of the following:  
+ <a name="legacy-subscription-router-component-configuration-subscription-target-cloud"></a>`cloud`. The `source` function publishes MQTT messages to AWS IoT Core.
+ <a name="legacy-subscription-router-component-configuration-subscription-source-target-component-name"></a>The name of a Lambda function component on the core device. Specify the component name with the `component:` prefix, such as **component:com.example.HelloWorldLambda**.
+ <a name="legacy-subscription-router-component-configuration-subscription-source-target-function-arn"></a>The Amazon Resource Name (ARN) of a Lambda function on the core device.
**Important**  <a name="legacy-subscription-router-function-version-requirement"></a>
If the version of the Lambda function changes, you must configure the subscription with the new version of the function. Otherwise, this component won't route the messages until the version matches the subscription.  
You must specify an Amazon Resource Name (ARN) that includes the version of the function to import. You can't use version aliases like `$LATEST`.
Default: No subscriptions

**Example configuration update (defining a subscription to AWS IoT Core)**  
The following example specifies that the `com.example.HelloWorldLambda` Lambda function component publishes MQTT message to AWS IoT Core on the `hello/world` topic.  

```
{
  "subscriptions": {
    "Greengrass_HelloWorld_to_cloud": {
      "id": "Greengrass_HelloWorld_to_cloud",
      "source": "component:com.example.HelloWorldLambda",
      "subject": "hello/world",
      "target": "cloud"
    }
  }
}
```

**Example configuration update (defining a subscription to another Lambda function)**  
The following example specifies that the `com.example.HelloWorldLambda` Lambda function component publishes MQTT messages to the `com.example.MessageRelay` Lambda function component on the `hello/world` topic.  

```
{
  "subscriptions": {
    "Greengrass_HelloWorld_to_MessageRelay": {
      "id": "Greengrass_HelloWorld_to_MessageRelay",
      "source": "component:com.example.HelloWorldLambda",
      "subject": "hello/world",
      "target": "component:com.example.MessageRelay"
    }
  }
}
```

------
#### [ v2.0.x ]

`subscriptions`  
<a name="legacy-subscription-router-component-configuration-subscriptions-intro"></a>(Optional) The subscriptions to enable on the core device. This is an object, where each key is a unique ID, and each value is an object that defines the subscription for that connector. You must configure a subscription when you deploy a V1 connector component or a Lambda function that uses the AWS IoT Greengrass Core SDK.  
Each subscription object contains the following information:    
`id`  <a name="legacy-subscription-router-component-configuration-subscription-id"></a>
The unique ID of this subscription. This ID must match the key for this subscription object.  
`source`  
The Lambda function that uses the AWS IoT Greengrass Core SDK to publish MQTT messages on the topics that you specify in `subject`. Specify the following:  
+ <a name="legacy-subscription-router-component-configuration-subscription-source-target-function-arn"></a>The Amazon Resource Name (ARN) of a Lambda function on the core device.
**Important**  <a name="legacy-subscription-router-function-version-requirement"></a>
If the version of the Lambda function changes, you must configure the subscription with the new version of the function. Otherwise, this component won't route the messages until the version matches the subscription.  
You must specify an Amazon Resource Name (ARN) that includes the version of the function to import. You can't use version aliases like `$LATEST`.
To deploy a subscription for a V1 connector component, specify the ARN of the connector component's Lambda function.  
`subject`  <a name="legacy-subscription-router-component-configuration-subscription-subject"></a>
The MQTT topic or topic filter on which the source and target can publish and receive messages. This value supports the `+` and `#` topic wildcards.  
`target`  
<a name="legacy-subscription-router-component-configuration-subscription-target-intro"></a>The target that receives the MQTT messages on the topics that you specify in `subject`. The subscription specifies that the `source` function publishes MQTT messages to AWS IoT Core or to a Lambda function on the core device. Specify one of the following:  
+ <a name="legacy-subscription-router-component-configuration-subscription-target-cloud"></a>`cloud`. The `source` function publishes MQTT messages to AWS IoT Core.
+ <a name="legacy-subscription-router-component-configuration-subscription-source-target-function-arn"></a>The Amazon Resource Name (ARN) of a Lambda function on the core device.
**Important**  <a name="legacy-subscription-router-function-version-requirement"></a>
If the version of the Lambda function changes, you must configure the subscription with the new version of the function. Otherwise, this component won't route the messages until the version matches the subscription.  
You must specify an Amazon Resource Name (ARN) that includes the version of the function to import. You can't use version aliases like `$LATEST`.
Default: No subscriptions

**Example configuration update (defining a subscription to AWS IoT Core)**  
The following example specifies that the `Greengrass_HelloWorld` function publishes MQTT message to AWS IoT Core on the `hello/world` topic.  

```
"subscriptions": {
  "Greengrass_HelloWorld_to_cloud": {
    "id": "Greengrass_HelloWorld_to_cloud",
    "source": "arn:aws:lambda:us-west-2:123456789012:function:Greengrass_HelloWorld:5",
    "subject": "hello/world",
    "target": "cloud"
  }
}
```

**Example configuration update (defining a subscription to another Lambda function)**  
The following example specifies that the `Greengrass_HelloWorld` function publishes MQTT messages to the `Greengrass_MessageRelay` on the `hello/world` topic.  

```
"subscriptions": {
  "Greengrass_HelloWorld_to_MessageRelay": {
    "id": "Greengrass_HelloWorld_to_MessageRelay",
    "source": "arn:aws:lambda:us-west-2:123456789012:function:Greengrass_HelloWorld:5",
    "subject": "hello/world",
    "target": "arn:aws:lambda:us-west-2:123456789012:function:Greengrass_MessageRelay:5"
  }
}
```

------

## Local log file


This component doesn't output logs.

## Changelog


The following table describes the changes in each version of the component.


|  Version  |  Changes  | 
| --- | --- | 
|  2.1.15  |  Version updated for Greengrass nucleus version 2.16.0 release.  | 
|  2.1.14  | Version updated for Greengrass nucleus version 2.15.0 release. | 
|  2.1.13  | Version updated for Greengrass nucleus version 2.14.0 release. | 
|  2.1.12  | Version updated for Greengrass nucleus version 2.13.0 release. | 
|  2.1.11  | Version updated for Greengrass nucleus version 2.12.0 release. | 
|  2.1.10  | Version updated for Greengrass nucleus version 2.11.0 release. | 
|  2.1.9  | Version updated for Greengrass nucleus version 2.10.0 release. | 
|  2.1.8  | Version updated for Greengrass nucleus version 2.9.0 release. | 
|  2.1.7  | Version updated for Greengrass nucleus version 2.8.0 release. | 
|  2.1.6  |  Version updated for Greengrass nucleus version 2.7.0 release.  | 
|  2.1.5  |  Version updated for Greengrass nucleus version 2.6.0 release.  | 
|  2.1.4  |  Version updated for Greengrass nucleus version 2.5.0 release.  | 
|  2.1.3  |  Version updated for Greengrass nucleus version 2.4.0 release.  | 
|  2.1.2  |  Version updated for Greengrass nucleus version 2.3.0 release.  | 
|  2.1.1  |  Version updated for Greengrass nucleus version 2.2.0 release.  | 
|  2.1.0  |  <a name="changelog-legacy-subscription-router-2.1.0"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/legacy-subscription-router-component.html)  | 
|  2.0.3  |  Initial version.  | 

# Local debug console
Local debug console v2.4.4 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/local-debug-console-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/local-debug-console-component.html)

Local debug console component v2.4.4 is available. This version includes general bug fixes and improvements.Local debug console v2.4.3 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/local-debug-console-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/local-debug-console-component.html)

Local debug console component v2.4.3 is available. This version includes general bug fixes and improvements.Local debug console v2.4.2 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/local-debug-console-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/local-debug-console-component.html)

Local debug console component v2.4.2 is available. This version includes general bug fixes and improvements.Local debug console v2.4.0 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/local-debug-console-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/local-debug-console-component.html)

Local debug console component v2.4.0 is available.

The local debug console component (`aws.greengrass.LocalDebugConsole`) provides a local dashboard that displays information about your AWS IoT Greengrass core devices and its components. You can use this dashboard to debug your core device and manage local components.

**Important**  
 <a name="local-dev-tools-production-environment-warning"></a>We recommend that you use this component in only development environments, not production environments. This component provides access to information and operations that you typically won't need in a production environment. Follow the principle of least privilege by deploying this component to only core devices where you need it. 

**Topics**
+ [

## Versions
](#local-debug-console-component-versions)
+ [

## Type
](#local-debug-console-component-type)
+ [

## Operating system
](#local-debug-console-component-os-support)
+ [

## Requirements
](#local-debug-console-component-requirements)
+ [

## Dependencies
](#local-debug-console-component-dependencies)
+ [

## Configuration
](#local-debug-console-component-configuration)
+ [

## Usage
](#local-debug-console-component-usage)
+ [

## Local log file
](#local-debug-console-component-log-file)
+ [

## Changelog
](#local-debug-console-component-changelog)

## Versions


This component has the following versions:
+ 2.4.x
+ 2.3.x
+ 2.2.x
+ 2.1.x
+ 2.0.x

## Type


<a name="public-component-type-plugin-para1"></a>This component is a plugin component (`aws.greengrass.plugin`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs this component in the same Java Virtual Machine (JVM) as the nucleus. The nucleus restarts when you change this component's version on the core device.

<a name="public-component-type-plugin-para2"></a>This component uses the same log file as the Greengrass nucleus. For more information, see [Monitor AWS IoT Greengrass logs](monitor-logs.md).

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on core devices that run the following operating systems:
+ Linux
+ Windows

## Requirements


This component has the following requirements:
+ You use a user name and password to sign in to the dashboard. The username, which is `debug`, is provided for you. You must use the AWS IoT Greengrass CLI to create a temporary password that authenticates you with the dashboard on a core device. You must be able to use the AWS IoT Greengrass CLI to use the local debug console. For more information, see the [Greengrass CLI requirements](greengrass-cli-component.md#greengrass-cli-component-requirements). For more information about how to generate the password and sign in, see [Local debug console component usage](#local-debug-console-component-usage).
+ The local debug console component is supported to run in a VPC.

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#local-debug-console-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

------
#### [ 2.4.6 ]

The following table lists the dependencies for version 2.4.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.10.0 <2.17.0 | Hard | 
| [Greengrass CLI](greengrass-cli-component.md) | >=2.10.0 <2.17.0 | Hard | 

------
#### [ 2.4.5 ]

The following table lists the dependencies for version 2.4.5 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.10.0 <2.16.0 | Hard | 
| [Greengrass CLI](greengrass-cli-component.md) | >=2.10.0 <2.16.0 | Hard | 

------
#### [ 2.4.4 ]

The following table lists the dependencies for version 2.4.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.10.0 <2.15.0 | Hard | 
| [Greengrass CLI](greengrass-cli-component.md) | >=2.10.0 <2.15.0 | Hard | 

------
#### [ 2.4.3 ]

The following table lists the dependencies for version 2.4.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.10.0 <2.14.0 | Hard | 
| [Greengrass CLI](greengrass-cli-component.md) | >=2.10.0 <2.14.0 | Hard | 

------
#### [ 2.4.1 – 2.4.2 ]

The following table lists the dependencies for versions 2.4.1 to 2.4.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.10.0 <2.13.0 | Hard | 
| [Greengrass CLI](greengrass-cli-component.md) | >=2.10.0 <2.13.0 | Hard | 

------
#### [ 2.4.0 ]

The following table lists the dependencies for version 2.4.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.10.0 <2.12.0 | Hard | 
| [Greengrass CLI](greengrass-cli-component.md) | >=2.10.0 <2.12.0 | Hard | 

------
#### [ 2.3.0 and 2.3.1 ]

The following table lists the dependencies for version 2.3.0 and 2.3.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.10.0 <2.12.0 | Hard | 
| [Greengrass CLI](greengrass-cli-component.md) | >=2.10.0 <2.12.0 | Hard | 

------
#### [ 2.2.9 ]

The following table lists the dependencies for version 2.2.9 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.12.0 | Hard | 
| [Greengrass CLI](greengrass-cli-component.md) | >=2.1.0 <2.12.0 | Hard | 

------
#### [ 2.2.8 ]

The following table lists the dependencies for version 2.2.8 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.11.0 | Hard | 
| [Greengrass CLI](greengrass-cli-component.md) | >=2.1.0 <2.11.0 | Hard | 

------
#### [ 2.2.7 ]

The following table lists the dependencies for version 2.2.7 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.10.0 | Hard | 
| [Greengrass CLI](greengrass-cli-component.md) | >=2.1.0 <2.10.0 | Hard | 

------
#### [ 2.2.6 ]

The following table lists the dependencies for version 2.2.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.9.0 | Hard | 
| [Greengrass CLI](greengrass-cli-component.md) | >=2.1.0 <2.9.0 | Hard | 

------
#### [ 2.2.5 ]

The following table lists the dependencies for version 2.2.5 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.8.0 | Hard | 
| [Greengrass CLI](greengrass-cli-component.md) | >=2.1.0 <2.8.0 | Hard | 

------
#### [ 2.2.4 ]

The following table lists the dependencies for version 2.2.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.7.0 | Hard | 
| [Greengrass CLI](greengrass-cli-component.md) | >=2.1.0 <2.7.0 | Hard | 

------
#### [ 2.2.3 ]

The following table lists the dependencies for version 2.2.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.6.0 | Hard | 
| [Greengrass CLI](greengrass-cli-component.md) | >=2.1.0 <2.6.0 | Hard | 

------
#### [ 2.2.2 ]

The following table lists the dependencies for version 2.2.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.5.0 | Hard | 
| [Greengrass CLI](greengrass-cli-component.md) | >=2.1.0 <2.5.0 | Hard | 

------
#### [ 2.2.1 ]

The following table lists the dependencies for version 2.2.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.4.0 | Hard | 
| [Greengrass CLI](greengrass-cli-component.md) | >=2.1.0 <2.4.0 | Hard | 

------
#### [ 2.2.0 ]

The following table lists the dependencies for version 2.2.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.3.0 | Hard | 
| [Greengrass CLI](greengrass-cli-component.md) | >=2.1.0 <2.3.0 | Hard | 

------
#### [ 2.1.0 ]

The following table lists the dependencies for version 2.1.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.2.0 | Hard | 
| [Greengrass CLI](greengrass-cli-component.md) | >=2.1.0 <2.2.0 | Hard | 

------
#### [ 2.0.x ]

The following table lists the dependencies for version 2.0.x of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.3 <2.1.0  | Soft | 
| [Greengrass CLI](greengrass-cli-component.md) |  >=2.0.3 <2.1.0  | Soft | 

------

For more information about component dependencies, see the [component recipe reference](component-recipe-reference.md#recipe-reference-component-dependencies).

## Configuration


This component provides the following configuration parameters that you can customize when you deploy the component.

------
#### [ v2.1.x - v2.4.x ]

`httpsEnabled`  
(Optional) You can enable HTTPS communication for the local debug console. If you enable HTTPS communication, the local debug console creates a self-signed certificate. Web browsers show security warnings for websites that use self-signed certificates, so you must manually verify the certificate. Then, you can bypass the warning. For more information, see [Usage](#local-debug-console-component-usage).  
Default: `true`

`port`  <a name="local-debug-console-component-configuration-port"></a>
(Optional) The port at which to provide the local debug console.  
Default: `1441`

`websocketPort`  <a name="local-debug-console-component-configuration-websocket-port"></a>
(Optional) The websocket port to use for the local debug console.  
Default: `1442`

`bindHostname`  <a name="local-debug-console-component-configuration-bind-hostname"></a>
(Optional) The hostname to use for the local debug console.  
If you [run the AWS IoT Greengrass Core software in a Docker container](run-greengrass-docker.md), set this parameter to `0.0.0.0`, so you can open the local debug console outside the Docker container.  
Default: `localhost`

**Example: Configuration merge update**  
The following example configuration specifies to open the local debug console on non-default ports and disable HTTPS.  

```
{
  "httpsEnabled": false,
  "port": "10441",
  "websocketPort": "10442"
}
```

------
#### [ v2.0.x ]

`port`  <a name="local-debug-console-component-configuration-port"></a>
(Optional) The port at which to provide the local debug console.  
Default: `1441`

`websocketPort`  <a name="local-debug-console-component-configuration-websocket-port"></a>
(Optional) The websocket port to use for the local debug console.  
Default: `1442`

`bindHostname`  <a name="local-debug-console-component-configuration-bind-hostname"></a>
(Optional) The hostname to use for the local debug console.  
If you [run the AWS IoT Greengrass Core software in a Docker container](run-greengrass-docker.md), set this parameter to `0.0.0.0`, so you can open the local debug console outside the Docker container.  
Default: `localhost`

**Example: Configuration merge update**  
The following example configuration specifies to open the local debug console on non-default ports.  

```
{
  "port": "10441",
  "websocketPort": "10442"
}
```

------

## Usage


To use the local debug console, create a session from the Greengrass CLI. When you create a session, the Greengrass CLI provides a user name and temporary password that you can use to sign in to the local debug console.

Follow these instructions to open the local debug console on your core device or on your development computer.

------
#### [ v2.1.x - v2.4.x ]

In versions 2.1.0 and later, the local debug console uses HTTPS by default. When HTTPS is enabled, the local debug console creates a self-signed certificate to secure the connection. Your web browser shows a security warning when you open the local debug console because of this self-signed certificate. When you create a session with the Greengrass CLI, the output includes the certificate's fingerprints, so you can verify that the certificate is legitimate and the connection is secure.

You can disable HTTPS. For more information, see [Local debug console configuration](#local-debug-console-component-configuration).

**To open the local debug console**

1. <a name="local-debug-console-component-usage-forward-port"></a>(Optional) To view the local debug console on your development computer, you can forward the console's port over SSH. However, you must first enable the `AllowTcpForwarding` option in your core device's SSH configuration file. This option is enabled by default. Run the following command on your development computer to view the dashboard at `localhost:1441` on your development computer.

   ```
   ssh -L 1441:localhost:1441 -L 1442:localhost:1442 username@core-device-ip-address
   ```
**Note**  
You can change the default ports from `1441` and `1442`. For more information, see [Local debug console configuration](#local-debug-console-component-configuration).

1. <a name="local-debug-console-component-create-session-step"></a>Create a session to use the local debug console. When you create a session, you generate a password that you use to authenticate. The local debug console requires a password to increase security, because you can use this component to view important information and perform operations on the core device. The local debug console also creates a certificate to secure the connection if you enable HTTPS in the component configuration. HTTPS is enabled by default.

   Use the AWS IoT Greengrass CLI to create the session. This command generates a random 43-character password that expires after 8 hours. Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the path to the AWS IoT Greengrass V2 root folder.

------
#### [ Linux or Unix ]

   ```
   sudo /greengrass/v2/bin/greengrass-cli get-debug-password
   ```

------
#### [ Windows ]

   ```
   C:\greengrass\v2\bin\greengrass-cli get-debug-password
   ```

------

   The command output looks like the following example if you have configured the local debug console to use HTTPS. You use the certificate fingerprints to verify that the connection is secure when you open the local debug console.

   ```
   Username: debug
   Password: bEDp3MOHdj8ou2w5de_sCBI2XAaguy3a8XxREXAMPLE
   Password expires at: 2021-04-01T17:01:43.921999931-07:00
   The local debug console is configured to use TLS security. The certificate is self-signed so you will need to bypass your web browser's security warnings to open the console.
   Before you bypass the security warning, verify that the certificate fingerprint matches the following fingerprints.
   SHA-256: 15 0B 2C E2 54 8B 22 DE 08 46 54 8A B1 2B 25 DE FB 02 7D 01 4E 4A 56 67 96 DA A6 CC B1 D2 C4 1B
   SHA-1: BC 3E 16 04 D3 80 70 DA E0 47 25 F9 90 FA D6 02 80 3E B5 C1
   ```

   The debug view component creates a session that lasts for 8 hours. After that, you must generate a new password to view the local debug console again. 

1. Open and sign in to the dashboard. View the dashboard on your Greengrass core device, or on your development computer if you forward the port over SSH. Do one of the following:
   + If you enabled HTTPS in the local debug console, which is the default setting, do the following:

     1. Open `https://localhost:1441` on your core device, or on your development computer if you forwarded the port over SSH.

        Your browser might show a security warning about an invalid security certificate.

     1. If your browser shows a security warning, verify the certificate is legitimate and bypass the security warning. Do the following:

        1. Find the SHA-256 or SHA-1 fingerprint for the certificate, and verify that it matches the SHA-256 or SHA-1 fingerprint that the `get-debug-password` command previously printed. Your browser might provide one or both fingerprints. Consult your browser's documentation to view the certificate and its fingerprints. In some browsers, the certificate fingerprint is called a thumbprint.
**Note**  
If the certificate fingerprint doesn't match, go to [Step 2](#local-debug-console-component-create-session-step) to create a new session. If the certificate fingerprint still doesn't match, your connection might be insecure.

        1. If the certificate fingerprint matches, bypass your browser's security warning to open the local debug console. Consult your browser's documentation to bypass the browser security warning.

     1. Sign in to the website using the user name and password that the `get-debug-password` command printed earlier.

        The local debug console opens.

     1. If the local debug console shows an error that says it can't connect to the WebSocket due to a failed TLS handshake, you must bypass the self-signed security warning for the WebSocket URL.  
![\[The WebSocket TLS handshake error in the local debug console.\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/images/local-debug-console/websocket-tls-handshake-error.png)

        Do the following:

        1. Open `https://localhost:1442` in the same browser where you opened the local debug console.

        1. Verify the certificate and bypass the security warning.

           Your browser might show an HTTP 404 page after you bypass the warning.

        1. Open `https://localhost:1441` again.

           The local debug console shows information about the core device.
   + If you disabled HTTPS in the local debug console, do the following:

     1. <a name="local-debug-console-component-usage-open-localhost-http"></a>Open `http://localhost:1441` on your core device, or open it on your development computer if you forwarded the port over SSH.

     1. <a name="local-debug-console-component-usage-sign-in"></a>Sign in to the website using the user name and password that the `get-debug-password` command previously printed.

        The local debug console opens.

------
#### [ v2.0.x ]

**To open the local debug console**

1. <a name="local-debug-console-component-usage-forward-port"></a>(Optional) To view the local debug console on your development computer, you can forward the console's port over SSH. However, you must first enable the `AllowTcpForwarding` option in your core device's SSH configuration file. This option is enabled by default. Run the following command on your development computer to view the dashboard at `localhost:1441` on your development computer.

   ```
   ssh -L 1441:localhost:1441 -L 1442:localhost:1442 username@core-device-ip-address
   ```
**Note**  
You can change the default ports from `1441` and `1442`. For more information, see [Local debug console configuration](#local-debug-console-component-configuration).

1. Create a session to use the local debug console. When you create a session, you generate a password that you use to authenticate. The local debug console requires a password to increase security, because you can use this component to view important information and perform operations on the core device.

   Use the AWS IoT Greengrass CLI to create the session. This command generates a random 43-character password that expires after 8 hours. Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the path to the AWS IoT Greengrass V2 root folder.

------
#### [ Linux or Unix ]

   ```
   sudo /greengrass/v2/bin/greengrass-cli get-debug-password
   ```

------
#### [ Windows ]

   ```
   C:\greengrass\v2\bin\greengrass-cli get-debug-password
   ```

------

   The command output looks like the following example.

   ```
   Username: debug
   Password: bEDp3MOHdj8ou2w5de_sCBI2XAaguy3a8XxREXAMPLE
   Password will expire at: 2021-04-01T17:01:43.921999931-07:00
   ```

   The debug view component creates a session lasts for 4 hours, and then you must generate a new password to view the local debug console again.

1. <a name="local-debug-console-component-usage-open-localhost-http"></a>Open `http://localhost:1441` on your core device, or open it on your development computer if you forwarded the port over SSH.

1. <a name="local-debug-console-component-usage-sign-in"></a>Sign in to the website using the user name and password that the `get-debug-password` command previously printed.

   The local debug console opens.

------

## Local log file


This component uses the same log file as the [Greengrass nucleus](greengrass-nucleus-component.md) component.

------
#### [ Linux ]

```
/greengrass/v2/logs/greengrass.log
```

------
#### [ Windows ]

```
C:\greengrass\v2\logs\greengrass.log
```

------

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the path to the AWS IoT Greengrass root folder.

------
#### [ Linux ]

  ```
  sudo tail -f /greengrass/v2/logs/greengrass.log
  ```

------
#### [ Windows (PowerShell) ]

  ```
  Get-Content C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
  ```

------

## Changelog


The following table describes the changes in each version of the component.


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.4.6  |  Version updated for Greengrass nucleus version 2.16.0 release.  | 
|  2.4.5  | Version updated for Greengrass nucleus version 2.15.0 release. | 
|  2.4.4  | Version updated for Greengrass nucleus version 2.14.0 release. | 
|  2.4.3  |  Version updated for Greengrass nucleus version 2.13.0 release. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/local-debug-console-component.html)  | 
|  2.4.2  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/local-debug-console-component.html)  | 
|  2.4.1  |  Version updated for Greengrass nucleus version 2.12.0 release.  | 
|  2.4.0  |  <a name="changelog-local-debug-console-2.4.0"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/local-debug-console-component.html)  | 
|  2.3.1  |  Version updated for Greengrass nucleus version 2.11.0 release.  | 
|  2.3.0  | Version updated for Greengrass nucleus version 2.10.0 release. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/local-debug-console-component.html) | 
|  2.2.7  | Version updated for Greengrass nucleus version 2.9.0 release. | 
|  2.2.6  | Version updated for Greengrass nucleus version 2.8.0 release. | 
|  2.2.5  |  Version updated for Greengrass nucleus version 2.7.0 release.  | 
|  2.2.4  |  Version updated for Greengrass nucleus version 2.6.0 release.  | 
|  2.2.3  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/local-debug-console-component.html)  | 
|  2.2.2  |  Version updated for Greengrass nucleus version 2.4.0 release.  | 
|  2.2.1  |  Version updated for Greengrass nucleus version 2.3.0 release.  | 
|  2.2.0  |  Version updated for Greengrass nucleus version 2.2.0 release.  | 
|  2.1.0  |  <a name="changelog-local-debug-console-2.1.0"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/local-debug-console-component.html)  | 
|  2.0.3  |  Initial version.  | 

# Log manager
Log manager v2.3.11 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html)

Log manager component v2.3.11 is available.Log manager v2.3.9 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html)

Log manager component v2.3.9 is available.Log manager v2.3.8 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html)

Log manager component v2.3.8 is available.Log manager v2.3.6 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html)

Log manager component v2.3.6 is available.Log manager v2.3.2 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html)

Log manager component v2.3.2 is available.Log manager v2.3.0 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html)

Log manager component v2.3.0 is available.Log manager v2.2.0 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html)

Log manager component v2.2.0 is available. Log manager now supports using a configuration map to provide component log configurations.

**Warning**  
We recommend upgrading to Log Manager v2.3.5 or later. Version 2.3.5 optimizes Log Manager configuration writes, reducing IO operations and improving log upload speed, overall device performance and possibly extending device life.

The log manager component (`aws.greengrass.LogManager`) uploads logs from AWS IoT Greengrass core devices to Amazon CloudWatch Logs. You can upload logs from the Greengrass nucleus, other Greengrass components, and other applications and services that aren't Greengrass components. For more information about how to monitor logs in CloudWatch Logs and on the local file system, see [Monitor AWS IoT Greengrass logs](monitor-logs.md).

<a name="log-manager-considerations-intro"></a>The following considerations apply when you use the log manager component to write to CloudWatch Logs:<a name="log-manager-considerations"></a>
+ **Log delays**

  The log manager component version 2.2.8 (and earlier) processes and uploads logs from only rotated log files. By default, the AWS IoT Greengrass Core software rotates log files every hour or after they are 1,024 KB. As a result, the log manager component uploads logs only after the AWS IoT Greengrass Core software or a Greengrass component writes over 1,024 KB worth of logs. You can configure a lower log file size limit to cause log files to rotate more often. This causes the log manager component to upload logs to CloudWatch Logs more frequently.

  The log manager component version 2.3.0 (and later) processes and uploads all logs. When you write a new log, log manager version 2.3.0 (and later) processes and directly uploads that active log file instead of waiting for it to be rotated. This means that you can view the new log in 5 minutes or less.

  The log manager component uploads new logs periodically. By default, the log manager component uploads new logs every 5 minutes. You can configure a lower upload interval, so the log manager component uploads logs to CloudWatch Logs more frequently by configuring the `periodicUploadIntervalSec`. For more information about how to configure this periodic interval, see [Configuration](https://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html#log-manager-component-configuration).

  Logs can be uploaded in near real-time from the same Greengrass file system. If you need to observe logs in real time, consider using [file system logs](monitor-logs.md#access-local-logs).
**Note**  
If you're using different file systems to write logs to, log manager reverts back to the behavior in log manager component versions 2.2.8 and earlier. For information about accessing file system logs, see [Access file system logs](https://docs.aws.amazon.com/greengrass/v2/developerguide/monitor-logs.html#access-local-logs).
+ **Clock skew**

  The log manager component uses the standard Signature Version 4 signing process to create API requests to CloudWatch Logs. If the system time on a core device is out of sync by more than 15 minutes, then CloudWatch Logs rejects the requests. For more information, see [Signature Version 4 signing process](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html) in the *AWS General Reference*.

For information about the log groups and log streams to which this component uploads logs, see [Usage](#log-manager-component-usage).

**Topics**
+ [

## Versions
](#log-manager-component-versions)
+ [

## Type
](#log-manager-component-type)
+ [

## Operating system
](#log-manager-component-os-support)
+ [

## Requirements
](#log-manager-component-requirements)
+ [

## Dependencies
](#log-manager-component-dependencies)
+ [

## Configuration
](#log-manager-component-configuration)
+ [

## Usage
](#log-manager-component-usage)
+ [

## Local log file
](#log-manager-component-log-file)
+ [

## Changelog
](#log-manager-component-changelog)

## Versions


This component has the following versions:
+ 2.3.x
+ 2.2.x
+ 2.1.x
+ 2.0.x

## Type


<a name="public-component-type-plugin-para1"></a>This component is a plugin component (`aws.greengrass.plugin`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs this component in the same Java Virtual Machine (JVM) as the nucleus. The nucleus restarts when you change this component's version on the core device.

<a name="public-component-type-plugin-para2"></a>This component uses the same log file as the Greengrass nucleus. For more information, see [Monitor AWS IoT Greengrass logs](monitor-logs.md).

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on core devices that run the following operating systems:
+ Linux
+ Windows

## Requirements


This component has the following requirements:
+ The [Greengrass device role](device-service-role.md) must allow the `logs:CreateLogGroup`, `logs:CreateLogStream`, `logs:PutLogEvents`, and `logs:DescribeLogStreams` actions, as shown in the following example IAM policy.

  ```
  {
    "Version": "2012-10-17",		 	 	 
    "Statement": [
      {
        "Action": [
          "logs:CreateLogGroup",
          "logs:CreateLogStream",
          "logs:PutLogEvents",
          "logs:DescribeLogStreams"
        ],
        "Effect": "Allow",
        "Resource": "arn:aws:logs:*:*:*"
      }
    ]
  }
  ```
**Note**  
The [Greengrass device role](device-service-role.md) that you create when you install the AWS IoT Greengrass Core software includes the permissions in this example policy by default.

  For more information, see [Using identity-based policies (IAM policies) for CloudWatch Logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/iam-identity-based-access-control-cwl.html) in the *Amazon CloudWatch Logs User Guide*.
+ The log manager component is supported to run in a VPC. To deploy this component in a VPC, the following is required.
  + The log manager component must have connectivity to `logs.region.amazonaws.com` which has the VPC endpoint of `com.amazonaws.us-east-1.logs`.

### Endpoints and ports


This component must be able to perform outbound requests to the following endpoints and ports, in addition to endpoints and ports required for basic operation. For more information, see [Allow device traffic through a proxy or firewall](allow-device-traffic.md).


| Endpoint | Port | Required | Description | 
| --- | --- | --- | --- | 
|  `logs.region.amazonaws.com`  | 443 | No |  Required if you write logs to CloudWatch Logs.  | 

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#log-manager-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

------
#### [ 2.3.11 ]

The following table lists the dependencies for version 2.3.11 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.17.0 | Soft | 

------
#### [ 2.3.10 ]

The following table lists the dependencies for version 2.3.10 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.16.0 | Soft | 

------
#### [ 2.3.9 ]

The following table lists the dependencies for version 2.3.9 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.15.0 | Soft | 

------
#### [ 2.3.8 ]

The following table lists the dependencies for version 2.3.8 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.14.0 | Soft | 

------
#### [ 2.3.7 ]

The following table lists the dependencies for version 2.3.7 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.13.0 | Soft | 

------
#### [ 2.3.5 and 2.3.6 ]

The following table lists the dependencies for versions 2.3.5 and 2.3.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.12.0 | Soft | 

------
#### [ 2.3.3 – 2.3.4 ]

The following table lists the dependencies for versions 2.3.3 to 2.3.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.11.0 | Soft | 

------
#### [ 2.2.8 – 2.3.2 ]

The following table lists the dependencies for versions 2.2.8 to 2.3.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.10.0 | Soft | 

------
#### [ 2.2.7 ]

The following table lists the dependencies for version 2.2.7 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.9.0 | Soft | 

------
#### [ 2.2.6 ]

The following table lists the dependencies for version 2.2.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.8.0 | Soft | 

------
#### [ 2.2.5 ]

The following table lists the dependencies for version 2.2.5 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.7.0 | Soft | 

------
#### [ 2.2.1 - 2.2.4 ]

The following table lists the dependencies for versions 2.2.1 - 2.2.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.6.0 | Soft | 

------
#### [ 2.1.3 and 2.2.0 ]

The following table lists the dependencies for versions 2.1.3 and 2.2.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.5.0 | Soft | 

------
#### [ 2.1.2 ]

The following table lists the dependencies for version 2.1.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.4.0 | Soft | 

------
#### [ 2.1.1 ]

The following table lists the dependencies for version 2.1.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.3.0 | Soft | 

------
#### [ 2.1.0 ]

The following table lists the dependencies for version 2.1.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.1.0 <2.2.0  | Soft | 

------
#### [ 2.0.x ]

The following table lists the dependencies for version 2.0.x of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.3 <2.1.0  | Soft | 

------

For more information about component dependencies, see the [component recipe reference](component-recipe-reference.md#recipe-reference-component-dependencies).

## Configuration


This component provides the following configuration parameters that you can customize when you deploy the component.

------
#### [ v2.3.10 ]

`logsUploaderConfiguration`  
(Optional) The configuration for logs that the log manager component uploads. This object contains the following information:    
  `systemLogsConfiguration`   
(Optional) The configuration for AWS IoT Greengrass Core software system logs, which include logs from the [Greengrass nucleus](greengrass-nucleus-component.md) and [plugin components](develop-greengrass-components.md#component-types). Specify this configuration to enable the log manager component to manage system logs. This object contains the following information:    
`uploadToCloudWatch`  <a name="log-manager-component-configuration-system-upload-to-cloud-watch"></a>
(Optional) You can upload system logs to CloudWatch Logs.  
Default: `false`  
`minimumLogLevel`  <a name="log-manager-component-configuration-system-minimum-log-level"></a>
(Optional) The minimum level of log messages to upload. This minimum level applies only if you configure the [Greengrass nucleus component](greengrass-nucleus-component.md) to output JSON format logs. To enable JSON format logs, specify `JSON` for the [logging format](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-logging-format) parameter (`logging.format`).  
Choose from the following log levels, listed here in level order:  <a name="nucleus-log-levels"></a>
+ `DEBUG`
+ `INFO`
+ `WARN`
+ `ERROR`
Default: `INFO`  
`diskSpaceLimit`  <a name="log-manager-component-configuration-system-disk-space-limit"></a>
(Optional) The maximum total size of Greengrass system log files, in the unit you specify in `diskSpaceLimitUnit`. After the total size of Greengrass system log files exceeds this maximum total size, the AWS IoT Greengrass Core software deletes the oldest Greengrass system log files.  
This parameter is equivalent to the [log size limit](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-system-logs-limit) parameter (`totalLogsSizeKB`) of the [Greengrass nucleus component](greengrass-nucleus-component.md). The AWS IoT Greengrass Core software uses the minimum of the two values as the maximum total Greengrass system log size.  
`diskSpaceLimitUnit`  <a name="log-manager-component-configuration-disk-space-limit-unit"></a>
(Optional) The unit for the `diskSpaceLimit`. Choose from the following options:  
+ `KB` – kilobytes
+ `MB` – megabytes
+ `GB` – gigabytes
Default: `KB`  
`deleteLogFileAfterCloudUpload`  <a name="log-manager-component-configuration-delete-log-file-after-cloud-upload"></a>
(Optional) You can delete a log file after the log manager component uploads the logs to CloudWatch Logs.  
Default: `false`  
  `componentLogsConfigurationMap`   
(Optional) A map of log configurations for components on the core device. Each `componentName` object in this map defines the log configuration for the component or application. The log manager component uploads these component logs to CloudWatch Logs.  
We strongly recommend using a single configuration key per component. You should only target a group of files that have only one log file that's actively being written to when using the `logFileRegex`. Not following this recommendation may lead to duplicate logs getting uploaded to CloudWatch. If you are targeting multiple active log files with a single regex, we recommend you upgrade to log manager v2.3.1 or later and consider changing your configuration using the [example configuration](#log-manager-multiple-logs-v2.3.10).
If you're upgrading from a version of log manager earlier than v2.2.0, you can continue to use the `componentLogsConfiguration` list instead of `componentLogsConfigurationMap`. However, we strongly recommend that you use the map format so that you can use merge and reset updates to modify configurations for specific components. For information about the `componentLogsConfiguration` parameter, see the configuration parameters for v2.1.x of this component.  
*`componentName`*  
The log configuration for the *`componentName`* component or application for this log configuration. You can specify the name of a Greengrass component or another value to identify this log group.  
Each object contains the following information:    
`minimumLogLevel`  <a name="log-manager-component-configuration-component-minimum-log-level"></a>
(Optional) The minimum level of log messages to upload. This minimum level applies only if this component's logs use a specific JSON format, which you can find in the [AWS IoT Greengrass logging module](https://github.com/aws-greengrass/aws-greengrass-logging-java) repository on GitHub.  
Choose from the following log levels, listed here in level order:  <a name="nucleus-log-levels"></a>
+ `DEBUG`
+ `INFO`
+ `WARN`
+ `ERROR`
Default: `INFO`  
`diskSpaceLimit`  <a name="log-manager-component-configuration-component-disk-space-limit"></a>
(Optional) The maximum total size of all log files for this component, in the unit you specify in `diskSpaceLimitUnit`. After the total size of this component's log files exceeds this maximum total size, the AWS IoT Greengrass Core software deletes this component's oldest log files.  
This parameter is related to the [log size limit](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-system-logs-limit) parameter (`totalLogsSizeKB`) of the [Greengrass nucleus component](greengrass-nucleus-component.md). The AWS IoT Greengrass Core software uses the minimum of the two values as the maximum total log size for this component.  
`diskSpaceLimitUnit`  <a name="log-manager-component-configuration-disk-space-limit-unit"></a>
(Optional) The unit for the `diskSpaceLimit`. Choose from the following options:  
+ `KB` – kilobytes
+ `MB` – megabytes
+ `GB` – gigabytes
Default: `KB`  
`logFileDirectoryPath`  <a name="log-manager-component-configuration-component-log-file-dir-path"></a>
(Optional) The path to the folder that contains this component's log files.  
You don't need to specify this parameter for Greengrass components that print to standard output (stdout) and standard error (stderr).  
Default: `/greengrass/v2/logs`.  
`logFileRegex`  <a name="log-manager-component-configuration-component-log-file-regex"></a>
(Optional) A regular expression that specifies the log file name format that the component or application uses. The log manager component uses this regular expression to identify log files in the folder at `logFileDirectoryPath`.  
You don't need to specify this parameter for Greengrass components that print to standard output (stdout) and standard error (stderr).  
If your component or application rotates log files, specify a regex that matches the rotated log file names. For example, you might specify **hello\$1world\$1\$1\$1\$1w\$1.log** to upload logs for a Hello World application. The `\\\\w*` pattern matches zero or more word characters, which includes alphanumeric characters and underscores. This regex matches log files with and without timestamps in their name. In this example, the log manager uploads the following log files:  
+ `hello_world.log` – The most recent log file for the Hello World application.
+ `hello_world_2020_12_15_17_0.log` – An older log file for the Hello World application.
Default: `componentName\\\\w*.log`, where *componentName* is the name of the component for this log configuration.  
`deleteLogFileAfterCloudUpload`  <a name="log-manager-component-configuration-delete-log-file-after-cloud-upload"></a>
(Optional) You can delete a log file after the log manager component uploads the logs to CloudWatch Logs.  
Default: `false`  
`multiLineStartPattern`  <a name="log-manager-component-configuration-component-multi-line-start-pattern"></a>
(Optional) A regular expression that identifies when a log message on a new line is a new log message. If the regular expression doesn't match the new line, the log manager component appends the new line to the log message for the previous line.  
By default, the log manager component checks if the line starts with a whitespace character, such as a tab or space. If it doesn't, the log manager handles that line as a new log message. Otherwise, it appends that line to the current log message. This behavior ensures that the log manager component doesn't split messages that span multiple lines, such as stack traces.

  `periodicUploadIntervalSec`   
(Optional) The period in seconds at which the log manager component checks for new log files to upload.  
Default: `300` (5 minutes)  
Minimum: `0.000001` (1 microsecond)

`updateToTlogIntervalSec`  
(Optional) The period in seconds for how often the nucleus writes Amazon CloudWatch Events log-upload event details to the local transaction log (`config.tlog`). Defaults to the value specified in `periodicUploadIntervalSec`. You can modify this parameter to increase the writing interval.  
Default: `periodicUploadIntervalSec`  
Minimum: `periodicUploadIntervalSec`

`deprecatedVersionSupport`  
Indicates whether the log manager should use logging speed improvements introduced in log manager v2.3.5. Set the value to `false` to use the improvements.  
If you set this value to `false` when you upgrade from log manager v2.3.1 or earlier duplicate log entries may be uploaded.  
The default is `true`.

**Example: Configuration merge update**  
The following example configuration specifies to upload system logs and `com.example.HelloWorld` component logs to CloudWatch Logs.  

```
{
  "logsUploaderConfiguration": {
    "systemLogsConfiguration": {
      "uploadToCloudWatch": "true",
      "minimumLogLevel": "INFO",
      "diskSpaceLimit": "10",
      "diskSpaceLimitUnit": "MB",
      "deleteLogFileAfterCloudUpload": "false"
    },
    "componentLogsConfigurationMap": {
      "com.example.HelloWorld": {
        "minimumLogLevel": "INFO",
        "diskSpaceLimit": "20",
        "diskSpaceLimitUnit": "MB",
        "deleteLogFileAfterCloudUpload": "false"
      }
    }
  },
  "periodicUploadIntervalSec": "300",
  "deprecatedVersionSupport": "false"
}
```

**Example: Configuration to upload multiple active log files using log manager v2.3.1**  
The following example configuration is the recommended example if you want to target multiple active log files. This example configuration specifies what active log files you want to upload to CloudWatch. Using this configuration example configuration will also upload any rotated files that match the `logFileRegex`. This example configuration is supported on log manager v2.3.1.  

```
{
  "logsUploaderConfiguration": {
    "componentLogsConfigurationMap": {
      "com.example.A": {
        "logFileRegex": "com.example.A\\w*.log",
        "deleteLogFileAfterCloudUpload": "false"
      }
      "com.example.B": {
        "logFileRegex": "com.example.B\\w*.log",
        "deleteLogFileAfterCloudUpload": "false"
      }
    }
  },
  "periodicUploadIntervalSec": "10"
}
```

------
#### [ v2.3.6 – v2.3.9 ]

`logsUploaderConfiguration`  
(Optional) The configuration for logs that the log manager component uploads. This object contains the following information:    
  `systemLogsConfiguration`   
(Optional) The configuration for AWS IoT Greengrass Core software system logs, which include logs from the [Greengrass nucleus](greengrass-nucleus-component.md) and [plugin components](develop-greengrass-components.md#component-types). Specify this configuration to enable the log manager component to manage system logs. This object contains the following information:    
`uploadToCloudWatch`  <a name="log-manager-component-configuration-system-upload-to-cloud-watch"></a>
(Optional) You can upload system logs to CloudWatch Logs.  
Default: `false`  
`minimumLogLevel`  <a name="log-manager-component-configuration-system-minimum-log-level"></a>
(Optional) The minimum level of log messages to upload. This minimum level applies only if you configure the [Greengrass nucleus component](greengrass-nucleus-component.md) to output JSON format logs. To enable JSON format logs, specify `JSON` for the [logging format](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-logging-format) parameter (`logging.format`).  
Choose from the following log levels, listed here in level order:  <a name="nucleus-log-levels"></a>
+ `DEBUG`
+ `INFO`
+ `WARN`
+ `ERROR`
Default: `INFO`  
`diskSpaceLimit`  <a name="log-manager-component-configuration-system-disk-space-limit"></a>
(Optional) The maximum total size of Greengrass system log files, in the unit you specify in `diskSpaceLimitUnit`. After the total size of Greengrass system log files exceeds this maximum total size, the AWS IoT Greengrass Core software deletes the oldest Greengrass system log files.  
This parameter is equivalent to the [log size limit](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-system-logs-limit) parameter (`totalLogsSizeKB`) of the [Greengrass nucleus component](greengrass-nucleus-component.md). The AWS IoT Greengrass Core software uses the minimum of the two values as the maximum total Greengrass system log size.  
`diskSpaceLimitUnit`  <a name="log-manager-component-configuration-disk-space-limit-unit"></a>
(Optional) The unit for the `diskSpaceLimit`. Choose from the following options:  
+ `KB` – kilobytes
+ `MB` – megabytes
+ `GB` – gigabytes
Default: `KB`  
`deleteLogFileAfterCloudUpload`  <a name="log-manager-component-configuration-delete-log-file-after-cloud-upload"></a>
(Optional) You can delete a log file after the log manager component uploads the logs to CloudWatch Logs.  
Default: `false`  
  `componentLogsConfigurationMap`   
(Optional) A map of log configurations for components on the core device. Each `componentName` object in this map defines the log configuration for the component or application. The log manager component uploads these component logs to CloudWatch Logs.  
We strongly recommend using a single configuration key per component. You should only target a group of files that have only one log file that's actively being written to when using the `logFileRegex`. Not following this recommendation may lead to duplicate logs getting uploaded to CloudWatch. If you are targeting multiple active log files with a single regex, we recommend you upgrade to log manager v2.3.1 or later and consider changing your configuration using the [example configuration](#log-manager-multiple-logs-v2.3.1).
If you're upgrading from a version of log manager earlier than v2.2.0, you can continue to use the `componentLogsConfiguration` list instead of `componentLogsConfigurationMap`. However, we strongly recommend that you use the map format so that you can use merge and reset updates to modify configurations for specific components. For information about the `componentLogsConfiguration` parameter, see the configuration parameters for v2.1.x of this component.  
*`componentName`*  
The log configuration for the *`componentName`* component or application for this log configuration. You can specify the name of a Greengrass component or another value to identify this log group.  
Each object contains the following information:    
`minimumLogLevel`  <a name="log-manager-component-configuration-component-minimum-log-level"></a>
(Optional) The minimum level of log messages to upload. This minimum level applies only if this component's logs use a specific JSON format, which you can find in the [AWS IoT Greengrass logging module](https://github.com/aws-greengrass/aws-greengrass-logging-java) repository on GitHub.  
Choose from the following log levels, listed here in level order:  <a name="nucleus-log-levels"></a>
+ `DEBUG`
+ `INFO`
+ `WARN`
+ `ERROR`
Default: `INFO`  
`diskSpaceLimit`  <a name="log-manager-component-configuration-component-disk-space-limit"></a>
(Optional) The maximum total size of all log files for this component, in the unit you specify in `diskSpaceLimitUnit`. After the total size of this component's log files exceeds this maximum total size, the AWS IoT Greengrass Core software deletes this component's oldest log files.  
This parameter is related to the [log size limit](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-system-logs-limit) parameter (`totalLogsSizeKB`) of the [Greengrass nucleus component](greengrass-nucleus-component.md). The AWS IoT Greengrass Core software uses the minimum of the two values as the maximum total log size for this component.  
`diskSpaceLimitUnit`  <a name="log-manager-component-configuration-disk-space-limit-unit"></a>
(Optional) The unit for the `diskSpaceLimit`. Choose from the following options:  
+ `KB` – kilobytes
+ `MB` – megabytes
+ `GB` – gigabytes
Default: `KB`  
`logFileDirectoryPath`  <a name="log-manager-component-configuration-component-log-file-dir-path"></a>
(Optional) The path to the folder that contains this component's log files.  
You don't need to specify this parameter for Greengrass components that print to standard output (stdout) and standard error (stderr).  
Default: `/greengrass/v2/logs`.  
`logFileRegex`  <a name="log-manager-component-configuration-component-log-file-regex"></a>
(Optional) A regular expression that specifies the log file name format that the component or application uses. The log manager component uses this regular expression to identify log files in the folder at `logFileDirectoryPath`.  
You don't need to specify this parameter for Greengrass components that print to standard output (stdout) and standard error (stderr).  
If your component or application rotates log files, specify a regex that matches the rotated log file names. For example, you might specify **hello\$1world\$1\$1\$1\$1w\$1.log** to upload logs for a Hello World application. The `\\\\w*` pattern matches zero or more word characters, which includes alphanumeric characters and underscores. This regex matches log files with and without timestamps in their name. In this example, the log manager uploads the following log files:  
+ `hello_world.log` – The most recent log file for the Hello World application.
+ `hello_world_2020_12_15_17_0.log` – An older log file for the Hello World application.
Default: `componentName\\\\w*.log`, where *componentName* is the name of the component for this log configuration.  
`deleteLogFileAfterCloudUpload`  <a name="log-manager-component-configuration-delete-log-file-after-cloud-upload"></a>
(Optional) You can delete a log file after the log manager component uploads the logs to CloudWatch Logs.  
Default: `false`  
`multiLineStartPattern`  <a name="log-manager-component-configuration-component-multi-line-start-pattern"></a>
(Optional) A regular expression that identifies when a log message on a new line is a new log message. If the regular expression doesn't match the new line, the log manager component appends the new line to the log message for the previous line.  
By default, the log manager component checks if the line starts with a whitespace character, such as a tab or space. If it doesn't, the log manager handles that line as a new log message. Otherwise, it appends that line to the current log message. This behavior ensures that the log manager component doesn't split messages that span multiple lines, such as stack traces.

  `periodicUploadIntervalSec`   
(Optional) The period in seconds at which the log manager component checks for new log files to upload.  
Default: `300` (5 minutes)  
Minimum: `0.000001` (1 microsecond)

`deprecatedVersionSupport`  
Indicates whether the log manager should use logging speed improvements introduced in log manager v2.3.5. Set the value to `false` to use the improvements.  
If you set this value to `false` when you upgrade from log manager v2.3.1 or earlier duplicate log entries may be uploaded.  
The default is `true`.

**Example: Configuration merge update**  
The following example configuration specifies to upload system logs and `com.example.HelloWorld` component logs to CloudWatch Logs.  

```
{
  "logsUploaderConfiguration": {
    "systemLogsConfiguration": {
      "uploadToCloudWatch": "true",
      "minimumLogLevel": "INFO",
      "diskSpaceLimit": "10",
      "diskSpaceLimitUnit": "MB",
      "deleteLogFileAfterCloudUpload": "false"
    },
    "componentLogsConfigurationMap": {
      "com.example.HelloWorld": {
        "minimumLogLevel": "INFO",
        "diskSpaceLimit": "20",
        "diskSpaceLimitUnit": "MB",
        "deleteLogFileAfterCloudUpload": "false"
      }
    }
  },
  "periodicUploadIntervalSec": "300",
  "deprecatedVersionSupport": "false"
}
```

**Example: Configuration to upload multiple active log files using log manager v2.3.1**  
The following example configuration is the recommended example if you want to target multiple active log files. This example configuration specifies what active log files you want to upload to CloudWatch. Using this configuration example configuration will also upload any rotated files that match the `logFileRegex`. This example configuration is supported on log manager v2.3.1.  

```
{
  "logsUploaderConfiguration": {
    "componentLogsConfigurationMap": {
      "com.example.A": {
        "logFileRegex": "com.example.A\\w*.log",
        "deleteLogFileAfterCloudUpload": "false"
      }
      "com.example.B": {
        "logFileRegex": "com.example.B\\w*.log",
        "deleteLogFileAfterCloudUpload": "false"
      }
    }
  },
  "periodicUploadIntervalSec": "10"
}
```

------
#### [ v2.3.0 – 2.3.5 ]

`logsUploaderConfiguration`  
(Optional) The configuration for logs that the log manager component uploads. This object contains the following information:    
  `systemLogsConfiguration`   
(Optional) The configuration for AWS IoT Greengrass Core software system logs, which include logs from the [Greengrass nucleus](greengrass-nucleus-component.md) and [plugin components](develop-greengrass-components.md#component-types). Specify this configuration to enable the log manager component to manage system logs. This object contains the following information:    
`uploadToCloudWatch`  <a name="log-manager-component-configuration-system-upload-to-cloud-watch"></a>
(Optional) You can upload system logs to CloudWatch Logs.  
Default: `false`  
`minimumLogLevel`  <a name="log-manager-component-configuration-system-minimum-log-level"></a>
(Optional) The minimum level of log messages to upload. This minimum level applies only if you configure the [Greengrass nucleus component](greengrass-nucleus-component.md) to output JSON format logs. To enable JSON format logs, specify `JSON` for the [logging format](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-logging-format) parameter (`logging.format`).  
Choose from the following log levels, listed here in level order:  <a name="nucleus-log-levels"></a>
+ `DEBUG`
+ `INFO`
+ `WARN`
+ `ERROR`
Default: `INFO`  
`diskSpaceLimit`  <a name="log-manager-component-configuration-system-disk-space-limit"></a>
(Optional) The maximum total size of Greengrass system log files, in the unit you specify in `diskSpaceLimitUnit`. After the total size of Greengrass system log files exceeds this maximum total size, the AWS IoT Greengrass Core software deletes the oldest Greengrass system log files.  
This parameter is equivalent to the [log size limit](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-system-logs-limit) parameter (`totalLogsSizeKB`) of the [Greengrass nucleus component](greengrass-nucleus-component.md). The AWS IoT Greengrass Core software uses the minimum of the two values as the maximum total Greengrass system log size.  
`diskSpaceLimitUnit`  <a name="log-manager-component-configuration-disk-space-limit-unit"></a>
(Optional) The unit for the `diskSpaceLimit`. Choose from the following options:  
+ `KB` – kilobytes
+ `MB` – megabytes
+ `GB` – gigabytes
Default: `KB`  
`deleteLogFileAfterCloudUpload`  <a name="log-manager-component-configuration-delete-log-file-after-cloud-upload"></a>
(Optional) You can delete a log file after the log manager component uploads the logs to CloudWatch Logs.  
Default: `false`  
  `componentLogsConfigurationMap`   
(Optional) A map of log configurations for components on the core device. Each `componentName` object in this map defines the log configuration for the component or application. The log manager component uploads these component logs to CloudWatch Logs.  
We strongly recommend using a single configuration key per component. You should only target a group of files that have only one log file that's actively being written to when using the `logFileRegex`. Not following this recommendation may lead to duplicate logs getting uploaded to CloudWatch. If you are targeting multiple active log files with a single regex, we recommend you upgrade to log manager v2.3.1 and consider changing your configuration using the [example configuration](#log-manager-multiple-logs-v2.3.1).
If you're upgrading from a version of log manager earlier than v2.2.0, you can continue to use the `componentLogsConfiguration` list instead of `componentLogsConfigurationMap`. However, we strongly recommend that you use the map format so that you can use merge and reset updates to modify configurations for specific components. For information about the `componentLogsConfiguration` parameter, see the configuration parameters for v2.1.x of this component.  
*`componentName`*  
The log configuration for the *`componentName`* component or application for this log configuration. You can specify the name of a Greengrass component or another value to identify this log group.  
Each object contains the following information:    
`minimumLogLevel`  <a name="log-manager-component-configuration-component-minimum-log-level"></a>
(Optional) The minimum level of log messages to upload. This minimum level applies only if this component's logs use a specific JSON format, which you can find in the [AWS IoT Greengrass logging module](https://github.com/aws-greengrass/aws-greengrass-logging-java) repository on GitHub.  
Choose from the following log levels, listed here in level order:  <a name="nucleus-log-levels"></a>
+ `DEBUG`
+ `INFO`
+ `WARN`
+ `ERROR`
Default: `INFO`  
`diskSpaceLimit`  <a name="log-manager-component-configuration-component-disk-space-limit"></a>
(Optional) The maximum total size of all log files for this component, in the unit you specify in `diskSpaceLimitUnit`. After the total size of this component's log files exceeds this maximum total size, the AWS IoT Greengrass Core software deletes this component's oldest log files.  
This parameter is related to the [log size limit](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-system-logs-limit) parameter (`totalLogsSizeKB`) of the [Greengrass nucleus component](greengrass-nucleus-component.md). The AWS IoT Greengrass Core software uses the minimum of the two values as the maximum total log size for this component.  
`diskSpaceLimitUnit`  <a name="log-manager-component-configuration-disk-space-limit-unit"></a>
(Optional) The unit for the `diskSpaceLimit`. Choose from the following options:  
+ `KB` – kilobytes
+ `MB` – megabytes
+ `GB` – gigabytes
Default: `KB`  
`logFileDirectoryPath`  <a name="log-manager-component-configuration-component-log-file-dir-path"></a>
(Optional) The path to the folder that contains this component's log files.  
You don't need to specify this parameter for Greengrass components that print to standard output (stdout) and standard error (stderr).  
Default: `/greengrass/v2/logs`.  
`logFileRegex`  <a name="log-manager-component-configuration-component-log-file-regex"></a>
(Optional) A regular expression that specifies the log file name format that the component or application uses. The log manager component uses this regular expression to identify log files in the folder at `logFileDirectoryPath`.  
You don't need to specify this parameter for Greengrass components that print to standard output (stdout) and standard error (stderr).  
If your component or application rotates log files, specify a regex that matches the rotated log file names. For example, you might specify **hello\$1world\$1\$1\$1\$1w\$1.log** to upload logs for a Hello World application. The `\\\\w*` pattern matches zero or more word characters, which includes alphanumeric characters and underscores. This regex matches log files with and without timestamps in their name. In this example, the log manager uploads the following log files:  
+ `hello_world.log` – The most recent log file for the Hello World application.
+ `hello_world_2020_12_15_17_0.log` – An older log file for the Hello World application.
Default: `componentName\\\\w*.log`, where *componentName* is the name of the component for this log configuration.  
`deleteLogFileAfterCloudUpload`  <a name="log-manager-component-configuration-delete-log-file-after-cloud-upload"></a>
(Optional) You can delete a log file after the log manager component uploads the logs to CloudWatch Logs.  
Default: `false`  
`multiLineStartPattern`  <a name="log-manager-component-configuration-component-multi-line-start-pattern"></a>
(Optional) A regular expression that identifies when a log message on a new line is a new log message. If the regular expression doesn't match the new line, the log manager component appends the new line to the log message for the previous line.  
By default, the log manager component checks if the line starts with a whitespace character, such as a tab or space. If it doesn't, the log manager handles that line as a new log message. Otherwise, it appends that line to the current log message. This behavior ensures that the log manager component doesn't split messages that span multiple lines, such as stack traces.

  `periodicUploadIntervalSec`   
(Optional) The period in seconds at which the log manager component checks for new log files to upload.  
Default: `300` (5 minutes)  
Minimum: `0.000001` (1 microsecond)

**Example: Configuration merge update**  
The following example configuration specifies to upload system logs and `com.example.HelloWorld` component logs to CloudWatch Logs.  

```
{
  "logsUploaderConfiguration": {
    "systemLogsConfiguration": {
      "uploadToCloudWatch": "true",
      "minimumLogLevel": "INFO",
      "diskSpaceLimit": "10",
      "diskSpaceLimitUnit": "MB",
      "deleteLogFileAfterCloudUpload": "false"
    },
    "componentLogsConfigurationMap": {
      "com.example.HelloWorld": {
        "minimumLogLevel": "INFO",
        "diskSpaceLimit": "20",
        "diskSpaceLimitUnit": "MB",
        "deleteLogFileAfterCloudUpload": "false"
      }
    }
  },
  "periodicUploadIntervalSec": "300"
}
```

**Example: Configuration to upload multiple active log files using log manager v2.3.1**  
The following example configuration is the recommended example if you want to target multiple active log files. This example configuration specifies what active log files you want to upload to CloudWatch. Using this configuration example configuration will also upload any rotated files that match the `logFileRegex`. This example configuration is supported on log manager v2.3.1.  

```
{
  "logsUploaderConfiguration": {
    "componentLogsConfigurationMap": {
      "com.example.A": {
        "logFileRegex": "com.example.A\\w*.log",
        "deleteLogFileAfterCloudUpload": "false"
      }
      "com.example.B": {
        "logFileRegex": "com.example.B\\w*.log",
        "deleteLogFileAfterCloudUpload": "false"
      }
    }
  },
  "periodicUploadIntervalSec": "10"
}
```

------
#### [ v2.2.x ]

`logsUploaderConfiguration`  
(Optional) The configuration for logs that the log manager component uploads. This object contains the following information:    
  `systemLogsConfiguration`   
(Optional) The configuration for AWS IoT Greengrass Core software system logs, which include logs from the [Greengrass nucleus](greengrass-nucleus-component.md) and [plugin components](develop-greengrass-components.md#component-types). Specify this configuration to enable the log manager component to manage system logs. This object contains the following information:    
`uploadToCloudWatch`  <a name="log-manager-component-configuration-system-upload-to-cloud-watch"></a>
(Optional) You can upload system logs to CloudWatch Logs.  
Default: `false`  
`minimumLogLevel`  <a name="log-manager-component-configuration-system-minimum-log-level"></a>
(Optional) The minimum level of log messages to upload. This minimum level applies only if you configure the [Greengrass nucleus component](greengrass-nucleus-component.md) to output JSON format logs. To enable JSON format logs, specify `JSON` for the [logging format](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-logging-format) parameter (`logging.format`).  
Choose from the following log levels, listed here in level order:  <a name="nucleus-log-levels"></a>
+ `DEBUG`
+ `INFO`
+ `WARN`
+ `ERROR`
Default: `INFO`  
`diskSpaceLimit`  <a name="log-manager-component-configuration-system-disk-space-limit"></a>
(Optional) The maximum total size of Greengrass system log files, in the unit you specify in `diskSpaceLimitUnit`. After the total size of Greengrass system log files exceeds this maximum total size, the AWS IoT Greengrass Core software deletes the oldest Greengrass system log files.  
This parameter is equivalent to the [log size limit](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-system-logs-limit) parameter (`totalLogsSizeKB`) of the [Greengrass nucleus component](greengrass-nucleus-component.md). The AWS IoT Greengrass Core software uses the minimum of the two values as the maximum total Greengrass system log size.  
`diskSpaceLimitUnit`  <a name="log-manager-component-configuration-disk-space-limit-unit"></a>
(Optional) The unit for the `diskSpaceLimit`. Choose from the following options:  
+ `KB` – kilobytes
+ `MB` – megabytes
+ `GB` – gigabytes
Default: `KB`  
`deleteLogFileAfterCloudUpload`  <a name="log-manager-component-configuration-delete-log-file-after-cloud-upload"></a>
(Optional) You can delete a log file after the log manager component uploads the logs to CloudWatch Logs.  
Default: `false`  
  `componentLogsConfigurationMap`   
(Optional) A map of log configurations for components on the core device. Each `componentName` object in this map defines the log configuration for the component or application. The log manager component uploads these component logs to CloudWatch Logs.  
If you're upgrading from a version of log manager earlier than v2.2.0, you can continue to use the `componentLogsConfiguration` list instead of `componentLogsConfigurationMap`. However, we strongly recommend that you use the map format so that you can use merge and reset updates to modify configurations for specific components. For information about the `componentLogsConfiguration` parameter, see the configuration parameters for v2.1.x of this component.   
*`componentName`*  
The log configuration for the *`componentName`* component or application for this log configuration. You can specify the name of a Greengrass component or another value to identify this log group.  
Each object contains the following information:    
`minimumLogLevel`  <a name="log-manager-component-configuration-component-minimum-log-level"></a>
(Optional) The minimum level of log messages to upload. This minimum level applies only if this component's logs use a specific JSON format, which you can find in the [AWS IoT Greengrass logging module](https://github.com/aws-greengrass/aws-greengrass-logging-java) repository on GitHub.  
Choose from the following log levels, listed here in level order:  <a name="nucleus-log-levels"></a>
+ `DEBUG`
+ `INFO`
+ `WARN`
+ `ERROR`
Default: `INFO`  
`diskSpaceLimit`  <a name="log-manager-component-configuration-component-disk-space-limit"></a>
(Optional) The maximum total size of all log files for this component, in the unit you specify in `diskSpaceLimitUnit`. After the total size of this component's log files exceeds this maximum total size, the AWS IoT Greengrass Core software deletes this component's oldest log files.  
This parameter is related to the [log size limit](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-system-logs-limit) parameter (`totalLogsSizeKB`) of the [Greengrass nucleus component](greengrass-nucleus-component.md). The AWS IoT Greengrass Core software uses the minimum of the two values as the maximum total log size for this component.  
`diskSpaceLimitUnit`  <a name="log-manager-component-configuration-disk-space-limit-unit"></a>
(Optional) The unit for the `diskSpaceLimit`. Choose from the following options:  
+ `KB` – kilobytes
+ `MB` – megabytes
+ `GB` – gigabytes
Default: `KB`  
`logFileDirectoryPath`  <a name="log-manager-component-configuration-component-log-file-dir-path"></a>
(Optional) The path to the folder that contains this component's log files.  
You don't need to specify this parameter for Greengrass components that print to standard output (stdout) and standard error (stderr).  
Default: `/greengrass/v2/logs`.  
`logFileRegex`  <a name="log-manager-component-configuration-component-log-file-regex"></a>
(Optional) A regular expression that specifies the log file name format that the component or application uses. The log manager component uses this regular expression to identify log files in the folder at `logFileDirectoryPath`.  
You don't need to specify this parameter for Greengrass components that print to standard output (stdout) and standard error (stderr).  
If your component or application rotates log files, specify a regex that matches the rotated log file names. For example, you might specify **hello\$1world\$1\$1\$1\$1w\$1.log** to upload logs for a Hello World application. The `\\\\w*` pattern matches zero or more word characters, which includes alphanumeric characters and underscores. This regex matches log files with and without timestamps in their name. In this example, the log manager uploads the following log files:  
+ `hello_world.log` – The most recent log file for the Hello World application.
+ `hello_world_2020_12_15_17_0.log` – An older log file for the Hello World application.
Default: `componentName\\\\w*.log`, where *componentName* is the name of the component for this log configuration.  
`deleteLogFileAfterCloudUpload`  <a name="log-manager-component-configuration-delete-log-file-after-cloud-upload"></a>
(Optional) You can delete a log file after the log manager component uploads the logs to CloudWatch Logs.  
Default: `false`  
`multiLineStartPattern`  <a name="log-manager-component-configuration-component-multi-line-start-pattern"></a>
(Optional) A regular expression that identifies when a log message on a new line is a new log message. If the regular expression doesn't match the new line, the log manager component appends the new line to the log message for the previous line.  
By default, the log manager component checks if the line starts with a whitespace character, such as a tab or space. If it doesn't, the log manager handles that line as a new log message. Otherwise, it appends that line to the current log message. This behavior ensures that the log manager component doesn't split messages that span multiple lines, such as stack traces.

  `periodicUploadIntervalSec`   
(Optional) The period in seconds at which the log manager component checks for new log files to upload.  
Default: `300` (5 minutes)  
Minimum: `0.000001` (1 microsecond)

**Example: Configuration merge update**  
The following example configuration specifies to upload system logs and `com.example.HelloWorld` component logs to CloudWatch Logs.  

```
{
  "logsUploaderConfiguration": {
    "systemLogsConfiguration": {
      "uploadToCloudWatch": "true",
      "minimumLogLevel": "INFO",
      "diskSpaceLimit": "10",
      "diskSpaceLimitUnit": "MB",
      "deleteLogFileAfterCloudUpload": "false"
    },
    "componentLogsConfigurationMap": {
      "com.example.HelloWorld": {
        "minimumLogLevel": "INFO",
        "diskSpaceLimit": "20",
        "diskSpaceLimitUnit": "MB",
        "deleteLogFileAfterCloudUpload": "false"
      }
    }
  },
  "periodicUploadIntervalSec": "300"
}
```

------
#### [ v2.1.x ]

`logsUploaderConfiguration`  
(Optional) The configuration for logs that the log manager component uploads. This object contains the following information:    
 `systemLogsConfiguration`   
(Optional) The configuration for AWS IoT Greengrass Core software system logs, which include logs from the [Greengrass nucleus](greengrass-nucleus-component.md) and [plugin components](develop-greengrass-components.md#component-types). Specify this configuration to enable the log manager component to manage system logs. This object contains the following information:    
`uploadToCloudWatch`  <a name="log-manager-component-configuration-system-upload-to-cloud-watch"></a>
(Optional) You can upload system logs to CloudWatch Logs.  
Default: `false`  
`minimumLogLevel`  <a name="log-manager-component-configuration-system-minimum-log-level"></a>
(Optional) The minimum level of log messages to upload. This minimum level applies only if you configure the [Greengrass nucleus component](greengrass-nucleus-component.md) to output JSON format logs. To enable JSON format logs, specify `JSON` for the [logging format](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-logging-format) parameter (`logging.format`).  
Choose from the following log levels, listed here in level order:  <a name="nucleus-log-levels"></a>
+ `DEBUG`
+ `INFO`
+ `WARN`
+ `ERROR`
Default: `INFO`  
`diskSpaceLimit`  <a name="log-manager-component-configuration-system-disk-space-limit"></a>
(Optional) The maximum total size of Greengrass system log files, in the unit you specify in `diskSpaceLimitUnit`. After the total size of Greengrass system log files exceeds this maximum total size, the AWS IoT Greengrass Core software deletes the oldest Greengrass system log files.  
This parameter is equivalent to the [log size limit](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-system-logs-limit) parameter (`totalLogsSizeKB`) of the [Greengrass nucleus component](greengrass-nucleus-component.md). The AWS IoT Greengrass Core software uses the minimum of the two values as the maximum total Greengrass system log size.  
`diskSpaceLimitUnit`  <a name="log-manager-component-configuration-disk-space-limit-unit"></a>
(Optional) The unit for the `diskSpaceLimit`. Choose from the following options:  
+ `KB` – kilobytes
+ `MB` – megabytes
+ `GB` – gigabytes
Default: `KB`  
`deleteLogFileAfterCloudUpload`  <a name="log-manager-component-configuration-delete-log-file-after-cloud-upload"></a>
(Optional) You can delete a log file after the log manager component uploads the logs to CloudWatch Logs.  
Default: `false`  
  `componentLogsConfiguration`   
(Optional) A list of log configurations for components on the core device. Each configuration in this list defines the log configuration for a component or application. The log manager component uploads these component logs to CloudWatch Logs  
Each object contains the following information:    
`componentName`  <a name="log-manager-component-configuration-component-component-name"></a>
The name of the component or application for this log configuration. You can specify the name of a Greengrass component or another value to identify this log group.  
`minimumLogLevel`  <a name="log-manager-component-configuration-component-minimum-log-level"></a>
(Optional) The minimum level of log messages to upload. This minimum level applies only if this component's logs use a specific JSON format, which you can find in the [AWS IoT Greengrass logging module](https://github.com/aws-greengrass/aws-greengrass-logging-java) repository on GitHub.  
Choose from the following log levels, listed here in level order:  <a name="nucleus-log-levels"></a>
+ `DEBUG`
+ `INFO`
+ `WARN`
+ `ERROR`
Default: `INFO`  
`diskSpaceLimit`  <a name="log-manager-component-configuration-component-disk-space-limit"></a>
(Optional) The maximum total size of all log files for this component, in the unit you specify in `diskSpaceLimitUnit`. After the total size of this component's log files exceeds this maximum total size, the AWS IoT Greengrass Core software deletes this component's oldest log files.  
This parameter is related to the [log size limit](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-system-logs-limit) parameter (`totalLogsSizeKB`) of the [Greengrass nucleus component](greengrass-nucleus-component.md). The AWS IoT Greengrass Core software uses the minimum of the two values as the maximum total log size for this component.  
`diskSpaceLimitUnit`  <a name="log-manager-component-configuration-disk-space-limit-unit"></a>
(Optional) The unit for the `diskSpaceLimit`. Choose from the following options:  
+ `KB` – kilobytes
+ `MB` – megabytes
+ `GB` – gigabytes
Default: `KB`  
`logFileDirectoryPath`  <a name="log-manager-component-configuration-component-log-file-dir-path"></a>
(Optional) The path to the folder that contains this component's log files.  
You don't need to specify this parameter for Greengrass components that print to standard output (stdout) and standard error (stderr).  
Default: `/greengrass/v2/logs`.  
`logFileRegex`  <a name="log-manager-component-configuration-component-log-file-regex"></a>
(Optional) A regular expression that specifies the log file name format that the component or application uses. The log manager component uses this regular expression to identify log files in the folder at `logFileDirectoryPath`.  
You don't need to specify this parameter for Greengrass components that print to standard output (stdout) and standard error (stderr).  
If your component or application rotates log files, specify a regex that matches the rotated log file names. For example, you might specify **hello\$1world\$1\$1\$1\$1w\$1.log** to upload logs for a Hello World application. The `\\\\w*` pattern matches zero or more word characters, which includes alphanumeric characters and underscores. This regex matches log files with and without timestamps in their name. In this example, the log manager uploads the following log files:  
+ `hello_world.log` – The most recent log file for the Hello World application.
+ `hello_world_2020_12_15_17_0.log` – An older log file for the Hello World application.
Default: `componentName\\\\w*.log`, where *componentName* is the name of the component for this log configuration.  
`deleteLogFileAfterCloudUpload`  <a name="log-manager-component-configuration-delete-log-file-after-cloud-upload"></a>
(Optional) You can delete a log file after the log manager component uploads the logs to CloudWatch Logs.  
Default: `false`  
`multiLineStartPattern`  <a name="log-manager-component-configuration-component-multi-line-start-pattern"></a>
(Optional) A regular expression that identifies when a log message on a new line is a new log message. If the regular expression doesn't match the new line, the log manager component appends the new line to the log message for the previous line.  
By default, the log manager component checks if the line starts with a whitespace character, such as a tab or space. If it doesn't, the log manager handles that line as a new log message. Otherwise, it appends that line to the current log message. This behavior ensures that the log manager component doesn't split messages that span multiple lines, such as stack traces.

 `periodicUploadIntervalSec`   
(Optional) The period in seconds at which the log manager component checks for new log files to upload.  
Default: `300` (5 minutes)  
Minimum: `0.000001` (1 microsecond)

**Example: Configuration merge update**  
The following example configuration specifies to upload system logs and `com.example.HelloWorld` component logs to CloudWatch Logs.  

```
{
  "logsUploaderConfiguration": {
    "systemLogsConfiguration": {
      "uploadToCloudWatch": "true",
      "minimumLogLevel": "INFO",
      "diskSpaceLimit": "10",
      "diskSpaceLimitUnit": "MB",
      "deleteLogFileAfterCloudUpload": "false"
    },
    "componentLogsConfiguration": [
      {
        "componentName": "com.example.HelloWorld",
        "minimumLogLevel": "INFO",
        "diskSpaceLimit": "20",
        "diskSpaceLimitUnit": "MB",
        "deleteLogFileAfterCloudUpload": "false"
      }
    ]
  },
  "periodicUploadIntervalSec": "300"
}
```

------
#### [ v2.0.x ]

`logsUploaderConfiguration`  
(Optional) The configuration for logs that the log manager component uploads. This object contains the following information:    
`systemLogsConfiguration`  
(Optional) The configuration for AWS IoT Greengrass Core software system logs. Specify this configuration to enable the log manager component to manage system logs. This object contains the following information:    
`uploadToCloudWatch`  <a name="log-manager-component-configuration-system-upload-to-cloud-watch"></a>
(Optional) You can upload system logs to CloudWatch Logs.  
Default: `false`  
`minimumLogLevel`  <a name="log-manager-component-configuration-system-minimum-log-level"></a>
(Optional) The minimum level of log messages to upload. This minimum level applies only if you configure the [Greengrass nucleus component](greengrass-nucleus-component.md) to output JSON format logs. To enable JSON format logs, specify `JSON` for the [logging format](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-logging-format) parameter (`logging.format`).  
Choose from the following log levels, listed here in level order:  <a name="nucleus-log-levels"></a>
+ `DEBUG`
+ `INFO`
+ `WARN`
+ `ERROR`
Default: `INFO`  
`diskSpaceLimit`  <a name="log-manager-component-configuration-system-disk-space-limit"></a>
(Optional) The maximum total size of Greengrass system log files, in the unit you specify in `diskSpaceLimitUnit`. After the total size of Greengrass system log files exceeds this maximum total size, the AWS IoT Greengrass Core software deletes the oldest Greengrass system log files.  
This parameter is equivalent to the [log size limit](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-system-logs-limit) parameter (`totalLogsSizeKB`) of the [Greengrass nucleus component](greengrass-nucleus-component.md). The AWS IoT Greengrass Core software uses the minimum of the two values as the maximum total Greengrass system log size.  
`diskSpaceLimitUnit`  <a name="log-manager-component-configuration-disk-space-limit-unit"></a>
(Optional) The unit for the `diskSpaceLimit`. Choose from the following options:  
+ `KB` – kilobytes
+ `MB` – megabytes
+ `GB` – gigabytes
Default: `KB`  
`deleteLogFileAfterCloudUpload`  <a name="log-manager-component-configuration-delete-log-file-after-cloud-upload"></a>
(Optional) You can delete a log file after the log manager component uploads the logs to CloudWatch Logs.  
Default: `false`  
`componentLogsConfiguration`  
(Optional) A list of log configurations for components on the core device. Each configuration in this list defines the log configuration for a component or application. The log manager component uploads these component logs to CloudWatch Logs  
Each object contains the following information:    
`componentName`  <a name="log-manager-component-configuration-component-component-name"></a>
The name of the component or application for this log configuration. You can specify the name of a Greengrass component or another value to identify this log group.  
`minimumLogLevel`  <a name="log-manager-component-configuration-component-minimum-log-level"></a>
(Optional) The minimum level of log messages to upload. This minimum level applies only if this component's logs use a specific JSON format, which you can find in the [AWS IoT Greengrass logging module](https://github.com/aws-greengrass/aws-greengrass-logging-java) repository on GitHub.  
Choose from the following log levels, listed here in level order:  <a name="nucleus-log-levels"></a>
+ `DEBUG`
+ `INFO`
+ `WARN`
+ `ERROR`
Default: `INFO`  
`diskSpaceLimit`  <a name="log-manager-component-configuration-component-disk-space-limit"></a>
(Optional) The maximum total size of all log files for this component, in the unit you specify in `diskSpaceLimitUnit`. After the total size of this component's log files exceeds this maximum total size, the AWS IoT Greengrass Core software deletes this component's oldest log files.  
This parameter is related to the [log size limit](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-system-logs-limit) parameter (`totalLogsSizeKB`) of the [Greengrass nucleus component](greengrass-nucleus-component.md). The AWS IoT Greengrass Core software uses the minimum of the two values as the maximum total log size for this component.  
`diskSpaceLimitUnit`  <a name="log-manager-component-configuration-disk-space-limit-unit"></a>
(Optional) The unit for the `diskSpaceLimit`. Choose from the following options:  
+ `KB` – kilobytes
+ `MB` – megabytes
+ `GB` – gigabytes
Default: `KB`  
`logFileDirectoryPath`  
The path to the folder that contains this component's log files.  
To upload a Greengrass component's logs, specify **`/greengrass/v2`/logs**, and replace `/greengrass/v2` with your Greengrass root folder.  
`logFileRegex`  
A regular expression that specifies the log file name format that the component or application uses. The log manager component uses this regular expression to identify log files in the folder at `logFileDirectoryPath`.  
To upload a Greengrass component's logs, specify a regex that matches the rotated log file names. For example, you might specify **com.example.HelloWorld\$1\$1w\$1.log** to upload logs for a Hello World component. The `\\w*` pattern matches zero or more word characters, which includes alphanumeric characters and underscores. This regex matches log files with and without timestamps in their name. In this example, the log manager uploads the following log files:  
+ `com.example.HelloWorld.log` – The most recent log file for the Hello World component.
+ `com.example.HelloWorld_2020_12_15_17_0.log` – An older log file for the Hello World component. The Greengrass nucleus adds a rotating timestamp to the log files.  
`deleteLogFileAfterCloudUpload`  <a name="log-manager-component-configuration-delete-log-file-after-cloud-upload"></a>
(Optional) You can delete a log file after the log manager component uploads the logs to CloudWatch Logs.  
Default: `false`  
`multiLineStartPattern`  <a name="log-manager-component-configuration-component-multi-line-start-pattern"></a>
(Optional) A regular expression that identifies when a log message on a new line is a new log message. If the regular expression doesn't match the new line, the log manager component appends the new line to the log message for the previous line.  
By default, the log manager component checks if the line starts with a whitespace character, such as a tab or space. If it doesn't, the log manager handles that line as a new log message. Otherwise, it appends that line to the current log message. This behavior ensures that the log manager component doesn't split messages that span multiple lines, such as stack traces.

`periodicUploadIntervalSec`  
(Optional) The period in seconds at which the log manager component checks for new log files to upload.  
Default: `300` (5 minutes)  
Minimum: `0.000001` (1 microsecond)

**Example: Configuration merge update**  
The following example configuration specifies to upload system logs and `com.example.HelloWorld` component logs to CloudWatch Logs.  

```
{
  "logsUploaderConfiguration": {
    "systemLogsConfiguration": {
      "uploadToCloudWatch": "true",
      "minimumLogLevel": "INFO",
      "diskSpaceLimit": "10",
      "diskSpaceLimitUnit": "MB",
      "deleteLogFileAfterCloudUpload": "false"
    },
    "componentLogsConfiguration": [
      {
        "componentName": "com.example.HelloWorld",
        "minimumLogLevel": "INFO",
        "logFileDirectoryPath": "/greengrass/v2/logs",
        "logFileRegex": "com.example.HelloWorld\\w*.log",
        "diskSpaceLimit": "20",
        "diskSpaceLimitUnit": "MB",
        "deleteLogFileAfterCloudUpload": "false"
      }
    ]
  },
  "periodicUploadIntervalSec": "300"
}
```

------

## Usage


The log manager component uploads to the following log groups and log streams.

------
#### [ 2.1.0 and later ]<a name="log-manager-log-group-stream-format"></a>

**Log group name**  

```
/aws/greengrass/componentType/region/componentName
```
The log group name uses the following variables:  
+ `componentType` – The type of the component, which can be one of the following:
  + `GreengrassSystemComponent` – This log group includes logs for the nucleus and plugin components, which run in the same JVM as the Greengrass nucleus. The component is part of the [Greengrass nucleus](greengrass-nucleus-component.md).
  + `UserComponent` – This log group includes logs for generic components, Lambda components, and other applications on the device. The component isn't part of the Greengrass nucleus.

  For more information, see [Component types](develop-greengrass-components.md#component-types).
+ `region` – The AWS Region that the core device uses.
+ `componentName` – The name of the component. For system logs, this value is `System`.

**Log stream name**  

```
/date/thing/thingName
```
The log stream name uses the following variables:  
+ `date` – The date of the log, such as `2020/12/15`. The log manager component uses the `yyyy/MM/dd` format.
+ `thingName` – The name of the core device.
If a thing name contains a colon (`:`), the log manager replaces the colon with a plus (`+`).

------
#### [ 2.0.x ]

**Log group name**  

```
/aws/greengrass/componentType/region/componentName
```
The log group name uses the following variables:  
+ `componentType` – The type of the component, which can be one of the following:
  + `GreengrassSystemComponent` – The component is part of the [Greengrass nucleus](greengrass-nucleus-component.md).
  + `UserComponent` – The component isn't part of the Greengrass nucleus. The log manager uses this type for Greengrass components and other applications on the device.
+ `region` – The AWS Region that the core device uses.
+ `componentName` – The name of the component. For system logs, this value is `System`.

**Log stream name**  

```
/date/deploymentTargets/thingName
```
The log stream name uses the following variables:  
+ `date` – The date of the log, such as `2020/12/15`. The log manager component uses the `yyyy/MM/dd` format.
+ `deploymentTargets` – The things whose deployments include the component. The log manager component separates each target by a slash. If the component runs on the core device as the result of a local deployment, this value is `LOCAL_DEPLOYMENT`.

  Consider an example where you have a core device named `MyGreengrassCore`, and the core device has two deployments:
  + A deployment that targets the core device, `MyGreengrassCore`.
  + A deployment that targets a thing group named `MyGreengrassCoreGroup`, which contains the core device.

  The `deploymentTargets` for this core device are `thing/MyGreengrassCore/thinggroup/MyGreengrassCoreGroup`.
+ `thingName` – The name of the core device.

------

### Formats for log entries.


The Greengrass nucleus writes log files in either string or JSON format. For system logs, you control the format by setting the `format` field of the `logging` entry. You can find the `logging` entry in the Greengrass nucleus component's configuration file. For more information, see [Greengrass nucleus configuration](https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html#greengrass-nucleus-component-configuration).

The text format is free-form and accepts any string. The following fleet status service message is an example of string formatted logging:

```
2023-03-26T18:18:27.271Z [INFO] (pool-1-thread-2)
com.aws.greengrass.status.FleetStatusService: fss-status-update-published. 
Status update published to FSS. {trigger=CADENCE, serviceName=FleetStatusService, 
currentState=RUNNING}
```

You should use the JSON format if you want to view logs with the [Greengrass CLI logs](https://docs.aws.amazon.com/greengrass/v2/developerguide/gg-cli-logs.html) command or interact with logs programmatically. The following example outlines the JSON shape:

```
{
   "loggerName": <string>,
   "level": <"DEBUG" | "INFO" | "ERROR" | "TRACE" | "WARN">,
   "eventType": <string, optional>,
   "cause": <string, optional>,
   "contexts": {},
   "thread": <string>,
   "message": <string>,
   "timestamp": <epoch time> # Needs to be epoch time
}
```

To control the output of your component's logs, you can use the `minimumLogLevel` configuration option. To use this option, your component must write its log entries in JSON format. You should use the same format as the system log file.

## Local log file


This component uses the same log file as the [Greengrass nucleus](greengrass-nucleus-component.md) component.

------
#### [ Linux ]

```
/greengrass/v2/logs/greengrass.log
```

------
#### [ Windows ]

```
C:\greengrass\v2\logs\greengrass.log
```

------

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the path to the AWS IoT Greengrass root folder.

------
#### [ Linux ]

  ```
  sudo tail -f /greengrass/v2/logs/greengrass.log
  ```

------
#### [ Windows (PowerShell) ]

  ```
  Get-Content C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
  ```

------

## Changelog


The following table describes the changes in each version of the component.


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.3.11  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html)  | 
|  2.3.10  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html)  | 
|  2.3.9  |  Version updated for Greengrass nucleus version 2.14.0 release.  | 
|  2.3.8  |  Version updated for Greengrass nucleus version 2.13.0 release.  | 
|  2.3.7  |  Version updated for Greengrass nucleus version 2.12.0 release.  | 
|  2.3.6  |  <a name="changelog-log-manager-2.3.6"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html)  | 
|  2.3.5  |  <a name="changelog-log-manager-2.3.5"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html) Version updated for Greengrass nucleus version 2.11.0 release.  | 
|  2.3.4  |  <a name="changelog-log-manager-2.3.4"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html)  | 
|  2.3.3  |  Version updated for Greengrass nucleus version 2.10.0 release.  | 
|  2.3.2  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html)  | 
|  2.3.1  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html)  | 
|  2.3.0  |   We recommend that you upgrade to Greengrass nucleus 2.9.1 when you upgrade to log manager 2.3.0.   [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html)  | 
|  2.2.8  | Version updated for Greengrass nucleus version 2.9.0 release. | 
|  2.2.7  | Version updated for Greengrass nucleus version 2.8.0 release. | 
|  2.2.6  |  Version updated for Greengrass nucleus version 2.7.0 release.  | 
|  2.2.5  |  Version updated for Greengrass nucleus version 2.6.0 release.  | 
|  2.2.4  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html)  | 
|  2.2.3  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html)  | 
|  2.2.2  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html)  | 
|  2.2.1  |  Version updated for Greengrass nucleus version 2.5.0 release.  | 
|  2.2.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html)  | 
|  2.1.3  |  Version updated for Greengrass nucleus version 2.4.0 release.  | 
|  2.1.2  |  Version updated for Greengrass nucleus version 2.3.0 release.  | 
|  2.1.1  |  <a name="changelog-log-manager-2.1.1"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html)  | 
|  2.1.0  |  <a name="changelog-log-manager-2.1.0"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/log-manager-component.html)  | 
|  2.0.x  |  Initial version.  | 

# Machine learning components
Machine learning components

AWS IoT Greengrass provides the following machine learning components that you can deploy to supported devices to [perform machine learning inference](perform-machine-learning-inference.md) using models trained in Amazon SageMaker AI or with your own pre-trained models that are stored in Amazon S3. <a name="ml-component-types"></a>

AWS provides the following categories of machine learning components:
+ **Model component**—Contains machine learning models as Greengrass artifacts.
+ **Runtime component**—Contains the script that installs the machine learning framework and its dependencies on the Greengrass core device.
+ **Inference component**—Contains the inference code and includes component dependencies to install the machine learning framework and download pre-trained machine learning models.

You can use the sample inference code and pre-trained models in the AWS-provided machine learning components to perform image classification and object detection using DLR and TensorFlow Lite. To perform custom machine learning inference with your own models that are stored in Amazon S3, or to use a different machine learning framework, you can use the recipes of these public components as templates to create custom machine learning components. For more information, see [Customize your machine learning components](ml-customization.md).

AWS IoT Greengrass also includes an AWS-provided component to manage the installation and lifecycle of the SageMaker AI Edge Manager agent on Greengrass core devices. With SageMaker AI Edge Manager, you can use Amazon SageMaker AI Neo-compiled models directly on your core device. For more information, see [Use Amazon SageMaker AI Edge Manager on Greengrass core devices](use-sagemaker-edge-manager.md).

The following table lists the machine learning components that are available in AWS IoT Greengrass. 

**Note**  <a name="component-nucleus-dependency-update-note"></a>
Several AWS-provided components depend on specific minor versions of the Greengrass nucleus. Because of this dependency, you need to update these components when you update the Greengrass nucleus to a new minor version. For information about the specific versions of the nucleus that each component depends on, see the corresponding component topic. For more information about updating the nucleus, see [Update the AWS IoT Greengrass Core software (OTA)](update-greengrass-core-v2.md).

<a name="component-table-type-description"></a>When a component has a component type of both generic and Lambda, the current version of the component is the generic type and a previous version of the component is the Lambda type.


| Component | Description | [Component type](develop-greengrass-components.md#component-types) | Supported OS | [Open source](open-source.md) | 
| --- | --- | --- | --- | --- | 
| [SageMaker AI Edge Manager](sagemaker-edge-manager-component.md) | Deploys the Amazon SageMaker AI Edge Manager agent on the Greengrass core device. | Generic | Linux, Windows | No | 
| [DLR image classification](dlr-image-classification-component.md) | Inference component that uses the DLR image classification model store and the DLR runtime component as dependencies to install DLR, download sample image classification models, and perform image classification inference on supported devices. | Generic | Linux, Windows | No | 
| [DLR object detection](dlr-object-detection-component.md) | Inference component that uses the DLR object detection model store and the DLR runtime component as dependencies to install DLR, download sample object detection models, and perform object detection inference on supported devices. | Generic | Linux, Windows | No | 
| [DLR image classification model store](dlr-image-classification-model-store-component.md) | Model component that contains sample ResNet-50 image classification models as Greengrass artifacts. | Generic | Linux, Windows | No | 
| [DLR object detection model store](dlr-object-detection-model-store-component.md) | Model component that contains sample YOLOv3 object detection models as Greengrass artifacts. | Generic | Linux, Windows | No | 
| [DLR runtime](dlr-component.md) | Runtime component that contains an installation script that is used to install DLR and its dependencies on the Greengrass core device. | Generic | Linux, Windows | No | 
| [TensorFlow Lite image classification](tensorflow-lite-image-classification-component.md) | Inference component that uses the TensorFlow Lite image classification model store and the TensorFlow Lite runtime component as dependencies to install TensorFlow Lite, download sample image classification models, and perform image classification inference on supported devices. | Generic | Linux, Windows | No | 
| [TensorFlow Lite object detection](tensorflow-lite-object-detection-component.md) | Inference component that uses the TensorFlow Lite object detection model store and the TensorFlow Lite runtime component as dependencies to install TensorFlow Lite, download sample object detection models, and perform object detection inference on supported devices. | Generic | Linux, Windows | No | 
| [TensorFlow Lite image classification model store](tensorflow-lite-image-classification-model-store-component.md) | Model component that contains a sample MobileNet v1 model as a Greengrass artifact. | Generic | Linux, Windows | No | 
| [TensorFlow Lite object detection model store](tensorflow-lite-object-detection-model-store-component.md) | Model component that contains a sample Single Shot Detection (SSD) MobileNet model as a Greengrass artifact. | Generic | Linux, Windows | No | 
| [TensorFlow Lite runtime](tensorflow-lite-component.md) | Runtime component that contains an installation script that is used to install TensorFlow Lite and its dependencies on the Greengrass core device. | Generic | Linux, Windows | No | 

# SageMaker AI Edge Manager
SageMaker AI Edge Manager discontinued[https://docs.aws.amazon.com//greengrass/v2/developerguide/sagemaker-edge-manager-component.html](https://docs.aws.amazon.com//greengrass/v2/developerguide/sagemaker-edge-manager-component.html)

Amazon SageMaker AI Edge Manager component is being discontinued on April 26, 2024.SageMaker AI Edge Manager v1.3.0 released[https://docs.aws.amazon.com//greengrass/v2/developerguide/sagemaker-edge-manager-component.html](https://docs.aws.amazon.com//greengrass/v2/developerguide/sagemaker-edge-manager-component.html)

Amazon SageMaker AI Edge Manager component v1.3.0 is available. This release adds support for this component to set the disk size for the TensorRT model cache, and improves prediction concurrency to make better use of device accelerator engines such as GPUs.SageMaker AI Edge Manager v1.2.0 released[https://docs.aws.amazon.com//greengrass/v2/developerguide/sagemaker-edge-manager-component.html](https://docs.aws.amazon.com//greengrass/v2/developerguide/sagemaker-edge-manager-component.html)

Amazon SageMaker AI Edge Manager component v1.2.0 is available. This release adds support for this component to automatically retrieve SageMaker AI Neo-compiled models that you upload to Amazon S3, so you can deploy new models without needing to create a AWS IoT Greengrass deployment.SageMaker AI Edge Manager v1.1.0 released[https://docs.aws.amazon.com//greengrass/v2/developerguide/sagemaker-edge-manager-component.html](https://docs.aws.amazon.com//greengrass/v2/developerguide/sagemaker-edge-manager-component.html)

Amazon SageMaker AI Edge Manager component v1.1.0 is available. This release adds support for Greengrass core devices running Amazon Linux 2, and adds a new configuration parameter to specify the location of the capture data folder on your device.SageMaker AI Edge Manager component v1.0.2 released[https://docs.aws.amazon.com//greengrass/v2/developerguide/sagemaker-edge-manager-component.html](https://docs.aws.amazon.com//greengrass/v2/developerguide/sagemaker-edge-manager-component.html)

Amazon SageMaker AI Edge Manager component v1.0.2 is available. This release updates the installation script in the component lifecycle. Your core devices must now have Python 3.6 or later, including `pip` for your version of Python, installed on the device before you deploy this component. New SageMaker AI Edge Manager component released[https://docs.aws.amazon.com//greengrass/v2/developerguide/sagemaker-edge-manager-component.html](https://docs.aws.amazon.com//greengrass/v2/developerguide/sagemaker-edge-manager-component.html)

Version 1.0.0 of the Amazon SageMaker AI Edge Manager component is available for AWS IoT Greengrass. This component installs the SageMaker AI Edge Manager agent binary on Greengrass core devices. 

**Important**  
SageMaker AI Edge Manager was discontinued on April 26th, 2024. For more information about continuing to deploy your models to edge devices, see [SageMaker AI Edge Manager end of life](https://docs.aws.amazon.com/sagemaker/latest/dg/edge-eol.html).

The Amazon SageMaker AI Edge Manager component (`aws.greengrass.SageMakerEdgeManager`) installs the SageMaker AI Edge Manager agent binary. 

SageMaker AI Edge Manager provides model management for edge devices so you can optimize, secure, monitor, and maintain machine learning models on fleets of edge devices. The SageMaker AI Edge Manager component installs and manages the lifecycle of the SageMaker AI Edge Manager agent on your core device. You can also use SageMaker AI Edge Manager to package and use SageMaker AI Neo-compiled models as model components on Greengrass core devices. For more information about using SageMaker AI Edge Manager agent on your core device, see [Use Amazon SageMaker AI Edge Manager on Greengrass core devices](use-sagemaker-edge-manager.md).

SageMaker AI Edge Manager component v1.3.x installs Edge Manager agent binary v1.20220822.836f3023. For more information about Edge Manager agent binary versions, see [Edge Manager Agent](https://docs.aws.amazon.com/sagemaker/latest/dg/edge-device-fleet-about).

**Note**  
The SageMaker AI Edge Manager component is available only in the following AWS Regions:  
US East (Ohio)
US East (N. Virginia)
US West (Oregon)
EU (Frankfurt)
EU (Ireland)
Asia Pacific (Tokyo)

**Topics**
+ [

## Versions
](#sagemaker-edge-manager-component-versions)
+ [

## Type
](#sagemaker-edge-manager-component-type)
+ [

## Operating system
](#sagemaker-edge-manager-component-os-support)
+ [

## Requirements
](#sagemaker-edge-manager-component-requirements)
+ [

## Dependencies
](#sagemaker-edge-manager-component-dependencies)
+ [

## Configuration
](#sagemaker-edge-manager-component-configuration)
+ [

## Local log file
](#sagemaker-edge-manager-component-log-file)
+ [

## Changelog
](#sagemaker-edge-manager-component-changelog)

## Versions


This component has the following versions:
+ 1.3.x
+ 1.2.x
+ 1.1.x
+ 1.0.x

## Type


<a name="public-component-type-generic"></a>This <a name="public-component-type-generic-phrase"></a>component is a generic component (`aws.greengrass.generic`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs the component's lifecycle scripts.

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on core devices that run the following operating systems:
+ Linux
+ Windows

## Requirements


This component has the following requirements:<a name="sm-edge-manager-component-reqs"></a>
+ <a name="sm-req-core-device"></a>A Greengrass core device running on Amazon Linux 2, a Debian-based Linux platform (x86\$164 or Armv8), or Windows (x86\$164). If you don't have one, see [Tutorial: Getting started with AWS IoT Greengrass V2](getting-started.md).
+ <a name="sm-req-python"></a>[Python](https://www.python.org/downloads/) 3.6 or later, including `pip` for your version of Python, installed on your core device.
+ The [Greengrass device role](device-service-role.md) configured with the following: 
  + <a name="sm-req-iam-trust-relationship"></a>A trust relationship that allows `credentials.iot.amazonaws.com` and `sagemaker.amazonaws.com` to assume the role, as shown in the following IAM policy example.

    ```
    { 
      "Version": "2012-10-17",		 	 	 
      "Statement": [ 
        { 
          "Effect": "Allow", 
          "Principal": {
            "Service": "credentials.iot.amazonaws.com"
           }, 
          "Action": "sts:AssumeRole" 
        },
        { 
          "Effect": "Allow", 
          "Principal": {
            "Service": "sagemaker.amazonaws.com"
          }, 
          "Action": "sts:AssumeRole" 
        } 
      ] 
    }
    ```
  + <a name="sm-req-iam-sagemanakeredgedevicefleetpolicy"></a>The [AmazonSageMakerEdgeDeviceFleetPolicy](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/service-role/AmazonSageMakerEdgeDeviceFleetPolicy) IAM managed policy.
  + <a name="sm-req-iam-s3-putobject"></a>The `s3:PutObject` action, as shown in the following IAM policy example.

    ```
    {
      "Version": "2012-10-17",		 	 	 
      "Statement": [
        {
          "Action": [
            "s3:PutObject"
          ],
          "Resource": [
            "*"
          ],
          "Effect": "Allow"
        }
      ]
    }
    ```
+ <a name="sm-req-s3-bucket"></a>An Amazon S3 bucket created in the same AWS account and AWS Region as your Greengrass core device. SageMaker AI Edge Manager requires an S3 bucket to create an edge device fleet, and to store sample data from running inference on your device. For information about creating S3 buckets, see [Getting started with Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/GetStartedWithS3.html).
+ <a name="sm-req-edge-device-fleet"></a>A SageMaker AI edge device fleet that uses the same AWS IoT role alias as your Greengrass core device. For more information, see [Create an edge device fleet](get-started-with-edge-manager-on-greengrass.md#create-edge-device-fleet-for-greengrass).
+ <a name="sm-req-edge-device"></a>Your Greengrass core device registered as an edge device in your SageMaker AI Edge device fleet. The edge device name must match the AWS IoT thing name for your core device. For more information, see [Register your Greengrass core device](get-started-with-edge-manager-on-greengrass.md#register-greengrass-core-device-in-sme).

### Endpoints and ports


This component must be able to perform outbound requests to the following endpoints and ports, in addition to endpoints and ports required for basic operation. For more information, see [Allow device traffic through a proxy or firewall](allow-device-traffic.md).


| Endpoint | Port | Required | Description | 
| --- | --- | --- | --- | 
|  `edge.sagemaker.region.amazonaws.com`  | 443 | Yes |  Check device registration status and send metrics to SageMaker AI.  | 
|  `*.s3.amazonaws.com`  | 443 | Yes |  Upload capture data to the S3 bucket that you specify. You can replace `*` with the name of each bucket where you upload data.  | 

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#sagemaker-edge-manager-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

------
#### [ 1.3.5 and 1.3.6 ]

The following table lists the dependencies for version 1.3.5 and 1.3.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.13.0 | Soft | 
| [Token exchange service](token-exchange-service-component.md) | >=0.0.0 | Hard | 

------
#### [ 1.3.4 ]

The following table lists the dependencies for version 1.3.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.12.0 | Soft | 
| [Token exchange service](token-exchange-service-component.md) | >=0.0.0 | Hard | 

------
#### [ 1.3.3 ]

The following table lists the dependencies for version 1.3.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.11.0 | Soft | 
| [Token exchange service](token-exchange-service-component.md) | >=0.0.0 | Hard | 

------
#### [ 1.3.2 ]

The following table lists the dependencies for version 1.3.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.10.0 | Soft | 
| [Token exchange service](token-exchange-service-component.md) | >=0.0.0 | Hard | 

------
#### [ 1.3.1 ]

The following table lists the dependencies for version 1.3.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.9.0 | Soft | 
| [Token exchange service](token-exchange-service-component.md) | >=0.0.0 | Hard | 

------
#### [ 1.1.1 - 1.3.0 ]

The following table lists the dependencies for versions 1.1.1 - 1.3.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.8.0 | Soft | 
| [Token exchange service](token-exchange-service-component.md) | >=0.0.0 | Hard | 

------
#### [ 1.1.0 ]

The following table lists the dependencies for version 1.1.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.6.0 | Soft | 
| [Token exchange service](token-exchange-service-component.md) | >=0.0.0 | Hard | 

------
#### [ 1.0.3 ]

The following table lists the dependencies for version 1.0.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.5.0 | Soft | 
| [Token exchange service](token-exchange-service-component.md) | >=0.0.0 | Hard | 

------
#### [ 1.0.1 and 1.0.2 ]

The following table lists the dependencies for versions 1.0.1 and 1.0.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.4.0 | Soft | 
| [Token exchange service](token-exchange-service-component.md) | >=0.0.0 | Hard | 

------
#### [ 1.0.0 ]

The following table lists the dependencies for version 1.0.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.3.0 | Soft | 
| [Token exchange service](token-exchange-service-component.md) | >=0.0.0 | Hard | 

------

For more information about component dependencies, see the [component recipe reference](component-recipe-reference.md#recipe-reference-component-dependencies).

## Configuration


This component provides the following configuration parameters that you can customize when you deploy the component.

**Note**  
This section describes the configuration parameters that you set in the component. For more information about the corresponding SageMaker AI Edge Manager configuration, see [Edge Manager Agent](https://docs.aws.amazon.com/sagemaker/latest/dg/edge-device-fleet-about.html#edge-device-fleet-running-agent) in the *Amazon SageMaker AI Developer Guide*.

`DeviceFleetName`  
The name of the SageMaker AI Edge Manager device fleet that contains your Greengrass core device.   
You must specify a value for this parameter in the configuration update when you deploy this component.

`BucketName`  
The name of the S3 bucket to which you upload captured inference data. The bucket name must contain the string `sagemaker`.   
If you set `CaptureDataDestination` to `Cloud`, or if you set `CaptureDataPeriodicUpload` to `true`, then you must specify a value for this parameter in the configuration update when you deploy this component.  
Capture data is an SageMaker AI feature that you use to upload inference input, inference results, and additional inference data to an S3 bucket or a local directory for future analysis. For more information about using capture data with SageMaker AI Edge Manager, see [Manage Model](https://docs.aws.amazon.com/sagemaker/latest/dg/edge-manage-model.html#edge-manage-model-capturedata) in the *Amazon SageMaker AI Developer Guide*.

`CaptureDataBatchSize`  
(Optional) The size of a batch of capture data requests that the agent handles. This value must be less than the buffer size that you specify in `CaptureDataBufferSize`. We recommend that you don't exceed half the buffer size.  
The agent handles a request batch when the number of requests in the buffer meets the `CaptureDataBatchSize` number, or when the `CaptureDataPushPeriodSeconds` interval elapses, whichever occurs first.  
Default: `10`

`CaptureDataBufferSize`  
(Optional) The maximum number of capture data requests stored in the buffer.  
Default: `30`

`CaptureDataDestination`  
(Optional) The destination where you store captured data. This parameter can have the following values:  
+ `Cloud`—Uploads captured data to the S3 bucket that you specify in `BucketName`.
+ `Disk`—Writes captured data to the component's work directory. 
If you specify `Disk`, you can also choose to periodically upload the captured data to your S3 bucket by setting `CaptureDataPeriodicUpload` to `true`.  
Default: `Cloud`

`CaptureDataPeriodicUpload`  
(Optional) String value that specifies whether to periodically upload captured data. Supported values are `true` and `false`.  
Set this parameter to `true` if you set `CaptureDataDestination` to `Disk`, and you also want the agent to periodically upload the captured data your S3 bucket.  
Default: `false`

`CaptureDataPeriodicUploadPeriodSeconds`  
(Optional) The interval in seconds at which SageMaker AI Edge Manager agent uploads captured data to the S3 bucket. Use this parameter if you set `CaptureDataPeriodicUpload` to `true`.  
Default: `8`

`CaptureDataPushPeriodSeconds`  
(Optional) The interval in seconds at which SageMaker AI Edge Manager agent handles a batch of capture data requests from the buffer.   
The agent handles a request batch when the number of requests in the buffer meets the `CaptureDataBatchSize` number, or when the `CaptureDataPushPeriodSeconds` interval elapses, whichever occurs first.  
Default: `4`

`CaptureDataBase64EmbedLimit`  
(Optional) The maximum size in bytes of captured data that SageMaker AI Edge Manager agent uploads.  
Default: `3072`

`FolderPrefix`  
(Optional) The name of the folder to which the agent writes the captured data. If you set `CaptureDataDestination` to `Disk`, the agent creates the folder in the directory that is specified by `CaptureDataDiskPath`. If you set `CaptureDataDestination` to `Cloud`, or if you set `CaptureDataPeriodicUpload` to `true`, the agent creates the folder in your S3 bucket.   
Default: `sme-capture`

`CaptureDataDiskPath`  
This feature is available in v1.1.0 and later versions of the SageMaker AI Edge Manager component.  
(Optional) The path to the folder to which the agent creates the captured data folder. If you set `CaptureDataDestination` to `Disk`, the agent creates the captured data folder in this directory. If you don't specify this value, the agent creates the captured data folder in the component's work directory. Use the `FolderPrefix` parameter to specify the name of the captured data folder.  
Default: `/greengrass/v2/work/aws.greengrass.SageMakerEdgeManager/capture`

`LocalDataRootPath`  
This feature is available in v1.2.0 and later versions of the SageMaker AI Edge Manager component.  
(Optional) The path where this component stores the following data on the core device:  
+ The local database for runtime data when you set `DbEnable` to `true`.
+ SageMaker AI Neo-compiled models that this component automatically downloads when you set `DeploymentEnable` to `true`.
Default: `/greengrass/v2/work/aws.greengrass.SageMakerEdgeManager`

`DbEnable`  
(Optional) You can enable this component to store runtime data in a local database to preserve the data, in case the component fails or the device loses power.  
This database requires 5 MB of storage on the core device's file system.  
Default: `false`

`DeploymentEnable`  
This feature is available in v1.2.0 and later versions of the SageMaker AI Edge Manager component.  
(Optional) You can enable this component to automatically retrieve SageMaker AI Neo-compiled models from that you upload to Amazon S3. After you upload a new model to Amazon S3, use SageMaker AI Studio or the SageMaker AI API to deploy the new model to this core device. When you enable this feature, you can deploy new models to core devices without needing to create a AWS IoT Greengrass deployment.  
To use this feature, you must set `DbEnable` to `true`. This feature uses the local database to track models that it retrieves from the AWS Cloud.
Default: `false`

`DeploymentPollInterval`  
This feature is available in v1.2.0 and later versions of the SageMaker AI Edge Manager component.  
(Optional) The amount of time (in minutes) between which this component checks for new models to download. This option applies when you set `DeploymentEnable` to `true`.  
Default: `1440` (1 day)

`DLRBackendOptions`  
This feature is available in v1.2.0 and later versions of the SageMaker AI Edge Manager component.  
(Optional) The DLR runtime flags to set in the DLR runtime that this component uses. You can set the following flag:  
+ `TVM_TENSORRT_CACHE_DIR` – Enable TensorRT model caching. Specify an absolute path to an existing folder that has read/write permissions.
+ `TVM_TENSORRT_CACHE_DISK_SIZE_MB` – Assigns the upper limit of the TensorRT model cache folder. When the directory size grows beyond this limit the cached engines that are used the least are deleted. The default value is 512 MB.
For example, you can set this parameter to the following value to enable TensorRT model caching and limit the cache size to 800 MB.  

```
TVM_TENSORRT_CACHE_DIR=/data/secured_folder/trt/cache; TVM_TENSORRT_CACHE_DISK_SIZE_MB=800
```

`SagemakerEdgeLogVerbose`  
(Optional) String value that specifies whether to enable debug logging. Supported values are `true` and `false`.  
Default: `false`

`UnixSocketName`  
(Optional) The location of the SageMaker AI Edge Manager socket file descriptor on the core device.  
Default: `/tmp/aws.greengrass.SageMakerEdgeManager.sock`

**Example: Configuration merge update**  
The following example configuration specifies that the core device is part of the *MyEdgeDeviceFleet* and that the agent writes capture data both to the device and to an S3 bucket. This configuration also enables debug logging.  

```
{
    "DeviceFleetName": "MyEdgeDeviceFleet",
    "BucketName": "amzn-s3-demo-bucket",
    "CaptureDataDestination": "Disk",
    "CaptureDataPeriodicUpload": "true",
    "SagemakerEdgeLogVerbose": "true"    
}
```

## Local log file


This component uses the following log file.

------
#### [ Linux ]

```
/greengrass/v2/logs/aws.greengrass.SageMakerEdgeManager.log
```

------
#### [ Windows ]

```
C:\greengrass\v2\logs\aws.greengrass.SageMakerEdgeManager.log
```

------

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the path to the AWS IoT Greengrass root folder.

------
#### [ Linux ]

  ```
  sudo tail -f /greengrass/v2/logs/aws.greengrass.SageMakerEdgeManager.log
  ```

------
#### [ Windows (PowerShell) ]

  ```
  Get-Content C:\greengrass\v2\logs\aws.greengrass.SageMakerEdgeManager.log -Tail 10 -Wait
  ```

------

## Changelog


The following table describes the changes in each version of the component.


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  1.3.6  |  Version updated for Greengrass nucleus 2.12.5 release.  | 
|  1.3.5  | Version updated for Greengrass nucleus version 2.12.0 release. | 
|  1.3.4  | Version updated for Greengrass nucleus version 2.11.0 release. | 
|  1.3.3  | Version updated for Greengrass nucleus version 2.10.0 release. | 
|  1.3.2  | Version updated for Greengrass nucleus version 2.9.0 release. | 
|  1.3.1  | Version updated for Greengrass nucleus version 2.8.0 release. | 
|  1.3.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/sagemaker-edge-manager-component.html)  | 
|  1.2.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/sagemaker-edge-manager-component.html)  | 
|  1.1.1  |  Version updated for Greengrass nucleus version 2.7.0 release.  | 
|  1.1.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/sagemaker-edge-manager-component.html)  | 
|  1.0.3  |  Version updated for Greengrass nucleus version 2.4.0 release.  | 
|  1.0.2  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/sagemaker-edge-manager-component.html)  | 
|  1.0.1  |  Version updated for Greengrass nucleus version 2.3.0 release.  | 
|  1.0.0  |  Initial version.  | 

# DLR image classification


The DLR image classification component (`aws.greengrass.DLRImageClassification`) contains sample inference code to perform image classification inference using [Deep Learning Runtime](https://github.com/neo-ai/neo-ai-dlr) and resnet-50 models. This component uses the variant [DLR image classification model store](dlr-image-classification-model-store-component.md) and the [DLR runtime](dlr-component.md) components as dependencies to download DLR and the sample models. 

To use this inference component with a custom-trained DLR model, [create a custom version](ml-customization.md#override-public-model-store) of the dependent model store component. To use your own custom inference code, you can use the recipe of this component as a template to [create a custom inference component](ml-customization.md#create-inference-component).

**Topics**
+ [

## Versions
](#dlr-image-classification-component-versions)
+ [

## Type
](#dlr-image-classification-component-type)
+ [

## Operating system
](#dlr-image-classification-component-os-support)
+ [

## Requirements
](#dlr-image-classification-component-requirements)
+ [

## Dependencies
](#dlr-image-classification-component-dependencies)
+ [

## Configuration
](#dlr-image-classification-component-configuration)
+ [

## Local log file
](#dlr-image-classification-component-log-file)
+ [

## Changelog
](#dlr-image-classification-component-changelog)

## Versions


This component has the following versions:
+ 2.1.x
+ 2.0.x

## Type


<a name="public-component-type-generic"></a>This <a name="public-component-type-generic-phrase"></a>component is a generic component (`aws.greengrass.generic`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs the component's lifecycle scripts.

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on core devices that run the following operating systems:
+ Linux
+ Windows

## Requirements


This component has the following requirements:<a name="ml-component-requirements"></a>
+ On Greengrass core devices running Amazon Linux 2 or Ubuntu 18.04, [GNU C Library](https://www.gnu.org/software/libc/) (glibc) version 2.27 or later installed on the device.
+ On Armv7l devices, such as Raspberry Pi, dependencies for OpenCV-Python installed on the device. Run the following command to install the dependencies.

  ```
  sudo apt-get install libopenjp2-7 libilmbase23 libopenexr-dev libavcodec-dev libavformat-dev libswscale-dev libv4l-dev libgtk-3-0 libwebp-dev
  ```
+ Raspberry Pi devices that run Raspberry Pi OS Bullseye must meet the following requirements:
  + NumPy 1.22.4 or later installed on the device. Raspberry Pi OS Bullseye includes an earlier version of NumPy, so you can run the following command to upgrade NumPy on the device.

    ```
    pip3 install --upgrade numpy
    ```
  + The legacy camera stack enabled on the device. Raspberry Pi OS Bullseye includes a new camera stack that is enabled by default and isn't compatible, so you must enable the legacy camera stack.<a name="raspberry-pi-bullseye-enable-legacy-camera-stack"></a>

**To enable the legacy camera stack**

    1. Run the following command to open the Raspberry Pi configuration tool.

       ```
       sudo raspi-config
       ```

    1. Select **Interface Options**.

    1. Select **Legacy camera** to enable the legacy camera stack.

    1. Reboot the Raspberry Pi.

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#dlr-image-classification-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

------
#### [ 2.1.13 and 2.1.14 ]

The following table lists the dependencies for version 2.1.13 and 2.1.14 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.13.0 | Soft | 
| [DLR image classification model store](dlr-image-classification-model-store-component.md) | \$12.1.0 | Hard | 
| [DLR](dlr-component.md) | \$11.6.0 | Hard | 

------
#### [ 2.1.12 ]

The following table lists the dependencies for version 2.1.12 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.12.0 | Soft | 
| [DLR image classification model store](dlr-image-classification-model-store-component.md) | \$12.1.0 | Hard | 
| [DLR](dlr-component.md) | \$11.6.0 | Hard | 

------
#### [ 2.1.11 ]

The following table lists the dependencies for version 2.1.11 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.11.0 | Soft | 
| [DLR image classification model store](dlr-image-classification-model-store-component.md) | \$12.1.0 | Hard | 
| [DLR](dlr-component.md) | \$11.6.0 | Hard | 

------
#### [ 2.1.10 ]

The following table lists the dependencies for version 2.1.10 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.10.0 | Soft | 
| [DLR image classification model store](dlr-image-classification-model-store-component.md) | \$12.1.0 | Hard | 
| [DLR](dlr-component.md) | \$11.6.0 | Hard | 

------
#### [ 2.1.9 ]

The following table lists the dependencies for version 2.1.9 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.9.0 | Soft | 
| [DLR image classification model store](dlr-image-classification-model-store-component.md) | \$12.1.0 | Hard | 
| [DLR](dlr-component.md) | \$11.6.0 | Hard | 

------
#### [ 2.1.8 ]

The following table lists the dependencies for version 2.1.8 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.8.0 | Soft | 
| [DLR image classification model store](dlr-image-classification-model-store-component.md) | \$12.1.0 | Hard | 
| [DLR](dlr-component.md) | \$11.6.0 | Hard | 

------
#### [ 2.1.7 ]

The following table lists the dependencies for version 2.1.7 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.7.0 | Soft | 
| [DLR image classification model store](dlr-image-classification-model-store-component.md) | \$12.1.0 | Hard | 
| [DLR](dlr-component.md) | \$11.6.0 | Hard | 

------
#### [ 2.1.6 ]

The following table lists the dependencies for version 2.1.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.6.0 | Soft | 
| [DLR image classification model store](dlr-image-classification-model-store-component.md) | \$12.1.0 | Hard | 
| [DLR](dlr-component.md) | \$11.6.0 | Hard | 

------
#### [ 2.1.4 - 2.1.5 ]

The following table lists the dependencies for versions 2.1.4 to 2.1.5 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.5.0 | Soft | 
| [DLR image classification model store](dlr-image-classification-model-store-component.md) | \$12.1.0 | Hard | 
| [DLR](dlr-component.md) | \$11.6.0 | Hard | 

------
#### [ 2.1.3 ]

The following table lists the dependencies for version 2.1.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.4.0 | Soft | 
| [DLR image classification model store](dlr-image-classification-model-store-component.md) | \$12.1.0 | Hard | 
| [DLR](dlr-component.md) | \$11.6.0 | Hard | 

------
#### [ 2.1.2 ]

The following table lists the dependencies for version 2.1.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.3.0 | Soft | 
| [DLR image classification model store](dlr-image-classification-model-store-component.md) | \$12.1.0 | Hard | 
| [DLR](dlr-component.md) | \$11.6.0 | Hard | 

------
#### [ 2.1.1 ]

The following table lists the dependencies for version 2.1.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.2.0 | Soft | 
| [DLR image classification model store](dlr-image-classification-model-store-component.md) | \$12.1.0 | Hard | 
| [DLR](dlr-component.md) | \$11.6.0 | Hard | 

------
#### [ 2.0.x ]

The following table lists the dependencies for version 2.0.x of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | \$12.0.0 | Soft | 
| DLR image classification model store | \$12.0.0 | Hard | 
| DLR | \$11.3.0 | Soft | 

------

## Configuration


This component provides the following configuration parameters that you can customize when you deploy the component.

------
#### [ 2.1.x ]

`accessControl`  
<a name="ml-config-accesscontrol-desc"></a>(Optional) The object that contains the [authorization policy](interprocess-communication.md#ipc-authorization-policies) that allows the component to publish messages to the default notifications topic.   
Default:   

```
{
   "aws.greengrass.ipc.mqttproxy": {
      "aws.greengrass.DLRImageClassification:mqttproxy:1": {
         "policyDescription": "Allows access to publish via topic ml/dlr/image-classification.",
         "operations": [
            "aws.greengrass#PublishToIoTCore"
         ],
         "resources": [
            "ml/dlr/image-classification"
         ]
      }
   }
}
```

`PublishResultsOnTopic`  
<a name="ml-config-publishresultsontopic-desc"></a>(Optional) The topic on which you want to publish the inference results. If you modify this value, then you must also modify the value of `resources` in the `accessControl` parameter to match your custom topic name.  
Default: `ml/dlr/image-classification`

`Accelerator`  <a name="ml-config-accelerator"></a>
The accelerator that you want to use. Supported values are `cpu` and `gpu`.  
The sample models in the dependent model component support only CPU acceleration. To use GPU acceleration with a different custom model, [create a custom model component](ml-customization.md#override-public-model-store) to override the public model component.  
Default: `cpu`

`ImageDirectory`  
<a name="ml-config-imagedirectory-desc"></a>(Optional) The path of the folder on the device where inference components read images. You can modify this value to any location on your device to which you have read/write access.  
<a name="ml-config-imagedirectory-img-default"></a>Default: `/greengrass/v2/packages/artifacts-unarchived/component-name/image_classification/sample_images/`  
If you set the value of `UseCamera` to `true`, then this configuration parameter is ignored. 

`ImageName`  
<a name="ml-config-imagename-desc"></a>(Optional) The name of the image that the inference component uses as an input to a make prediction. The component looks for the image in the folder specified in `ImageDirectory`. By default, the component uses the sample image in the default image directory. AWS IoT Greengrass supports the following image formats: `jpeg`, `jpg`, `png`, and `npy`.   
<a name="ml-config-imagename-img-default"></a>Default: `cat.jpeg`  
If you set the value of `UseCamera` to `true`, then this configuration parameter is ignored. 

`InferenceInterval`  <a name="ml-config-inferenceinterval"></a>
(Optional) The time in seconds between each prediction made by the inference code. The sample inference code runs indefinitely and repeats its predictions at the specified time interval. For example, you can change this to a shorter interval if you want to use images taken by a camera for real-time prediction.  
Default: `3600`

`ModelResourceKey`  <a name="ml-config-modelresourcekey"></a>
<a name="ml-config-modelresourcekey-desc"></a>(Optional) The models that are used in the dependent public model component. Modify this parameter only if you override the public model component with a custom component.   
Default:  

```
{
    "armv7l": "DLR-resnet50-armv7l-cpu-ImageClassification",
    "aarch64": "DLR-resnet50-aarch64-cpu-ImageClassification",
    "x86_64": "DLR-resnet50-x86_64-cpu-ImageClassification",
    "windows": "DLR-resnet50-win-cpu-ImageClassification"
}
```

`UseCamera`  <a name="ml-config-usecamera"></a>
(Optional) String value that defines whether to use images from a camera connected to the Greengrass core device. Supported values are `true` and `false`.  
When you set this value to `true`, the sample inference code accesses the camera on your device and runs inference locally on the captured image. The values of the `ImageName` and `ImageDirectory` parameters are ignored. Make sure that the user running this component has read/write access to the location where the camera stores captured images.  
Default: `false`  
When you view the recipe of this component, the `UseCamera` configuration parameter doesn't appear in the default configuration. However, you can modify the value of this parameter in a [configuration merge update](update-component-configurations.md) when you deploy the component.   
When you set `UseCamera` to `true`, you must also create a symlink to enable the inference component to access your camera from the virtual environment that is created by the runtime component. For more information about using a camera with the sample inference components, see [Update component configurations](ml-tutorial-image-classification-camera.md).

------
#### [ 2.0.x ]

`MLRootPath`  <a name="ml-config-mlrootpath"></a>
<a name="ml-config-mlrootpath-desc"></a>(Optional) The path of the folder on Linux core devices where inference components read images and write inference results. You can modify this value to any location on your device to which the user running this component has read/write access.  
<a name="ml-config-mlrootpath-default-dlr"></a>Default: `/greengrass/v2/work/variant.DLR/greengrass_ml`  
<a name="ml-config-mlrootpath-default-tfl"></a>Default: `/greengrass/v2/work/variant.TensorFlowLite/greengrass_ml`

`Accelerator`  <a name="ml-config-accelerator"></a>
The accelerator that you want to use. Supported values are `cpu` and `gpu`.  
The sample models in the dependent model component support only CPU acceleration. To use GPU acceleration with a different custom model, [create a custom model component](ml-customization.md#override-public-model-store) to override the public model component.  
Default: `cpu`

`ImageName`  
<a name="ml-config-imagename-desc-dlr-1.3.0"></a>(Optional) The name of the image that the inference component uses as an input to a make prediction. The component looks for the image in the folder specified in `ImageDirectory`. The default location is `MLRootPath/images`. AWS IoT Greengrass supports the following image formats: `jpeg`, `jpg`, `png`, and `npy`.   
<a name="ml-config-imagename-img-default"></a>Default: `cat.jpeg`

`InferenceInterval`  <a name="ml-config-inferenceinterval"></a>
(Optional) The time in seconds between each prediction made by the inference code. The sample inference code runs indefinitely and repeats its predictions at the specified time interval. For example, you can change this to a shorter interval if you want to use images taken by a camera for real-time prediction.  
Default: `3600`

`ModelResourceKey`  <a name="ml-config-modelresourcekey"></a>
<a name="ml-config-modelresourcekey-desc"></a>(Optional) The models that are used in the dependent public model component. Modify this parameter only if you override the public model component with a custom component.   
Default:  

```
armv7l: "DLR-resnet50-armv7l-cpu-ImageClassification"
x86_64: "DLR-resnet50-x86_64-cpu-ImageClassification"
```

------

## Local log file


This component uses the following log file.

------
#### [ Linux ]

```
/greengrass/v2/logs/aws.greengrass.DLRImageClassification.log
```

------
#### [ Windows ]

```
C:\greengrass\v2\logs\aws.greengrass.DLRImageClassification.log
```

------

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the path to the AWS IoT Greengrass root folder.

------
#### [ Linux ]

  ```
  sudo tail -f /greengrass/v2/logs/aws.greengrass.DLRImageClassification.log
  ```

------
#### [ Windows (PowerShell) ]

  ```
  Get-Content C:\greengrass\v2\logs\aws.greengrass.DLRImageClassification.log -Tail 10 -Wait
  ```

------

## Changelog


The following table describes the changes in each version of the component.


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.1.14  | Version updated for Greengrass nucleus 2.12.5 release. | 
|  2.1.13  | Version updated for Greengrass nucleus version 2.12.0 release. | 
|  2.1.12  | Version updated for Greengrass nucleus version 2.11.0 release. | 
|  2.1.11  | Version updated for Greengrass nucleus version 2.10.0 release. | 
|  2.1.10  | Version updated for Greengrass nucleus version 2.9.0 release. | 
|  2.1.9  | Version updated for Greengrass nucleus version 2.8.0 release. | 
|  2.1.8  |  Version updated for Greengrass nucleus version 2.7.0 release.  | 
|  2.1.7  |  Version updated for Greengrass nucleus version 2.6.0 release.  | 
|  2.1.6  |  Version updated for Greengrass nucleus version 2.5.0 release.  | 
|  2.1.5  |  Component released in all AWS Regions.  | 
|  2.1.4  |  Version updated for Greengrass nucleus version 2.4.0 release. This version isn't available in Europe (London) (`eu-west-2`).  | 
|  2.1.3  |  Version updated for Greengrass nucleus version 2.3.0 release.  | 
|  2.1.2  |  Version updated for Greengrass nucleus version 2.2.0 release.  | 
|  2.1.1  |  <a name="changelog-dlr-image-classification-2.1.1"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/dlr-image-classification-component.html)  | 
|  2.0.4  |  Initial version.  | 

# DLR object detection


The DLR object detection component (`aws.greengrass.DLRObjectDetection`) contains sample inference code to perform object detection inference using [Deep Learning Runtime](https://github.com/neo-ai/neo-ai-dlr) and sample pre-trained models. This component uses the variant [DLR object detection model store](dlr-object-detection-model-store-component.md) and the [DLR runtime](dlr-component.md) components as dependencies to download DLR and the sample models. 

To use this inference component with a custom-trained DLR model, [create a custom version](ml-customization.md#override-public-model-store) of the dependent model store component. To use your own custom inference code, you can use the recipe of this component as a template to [create a custom inference component](ml-customization.md#create-inference-component).

**Topics**
+ [

## Versions
](#dlr-object-detection-component-versions)
+ [

## Type
](#dlr-object-detection-component-type)
+ [

## Operating system
](#dlr-object-detection-component-os-support)
+ [

## Requirements
](#dlr-object-detection-component-requirements)
+ [

## Dependencies
](#dlr-object-detection-component-dependencies)
+ [

## Configuration
](#dlr-object-detection-component-configuration)
+ [

## Local log file
](#dlr-object-detection-component-log-file)
+ [

## Changelog
](#dlr-object-detection-component-changelog)

## Versions


This component has the following versions:
+ 2.1.x
+ 2.0.x

## Type


<a name="public-component-type-generic"></a>This <a name="public-component-type-generic-phrase"></a>component is a generic component (`aws.greengrass.generic`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs the component's lifecycle scripts.

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on core devices that run the following operating systems:
+ Linux
+ Windows

## Requirements


This component has the following requirements:<a name="ml-component-requirements"></a>
+ On Greengrass core devices running Amazon Linux 2 or Ubuntu 18.04, [GNU C Library](https://www.gnu.org/software/libc/) (glibc) version 2.27 or later installed on the device.
+ On Armv7l devices, such as Raspberry Pi, dependencies for OpenCV-Python installed on the device. Run the following command to install the dependencies.

  ```
  sudo apt-get install libopenjp2-7 libilmbase23 libopenexr-dev libavcodec-dev libavformat-dev libswscale-dev libv4l-dev libgtk-3-0 libwebp-dev
  ```
+ Raspberry Pi devices that run Raspberry Pi OS Bullseye must meet the following requirements:
  + NumPy 1.22.4 or later installed on the device. Raspberry Pi OS Bullseye includes an earlier version of NumPy, so you can run the following command to upgrade NumPy on the device.

    ```
    pip3 install --upgrade numpy
    ```
  + The legacy camera stack enabled on the device. Raspberry Pi OS Bullseye includes a new camera stack that is enabled by default and isn't compatible, so you must enable the legacy camera stack.<a name="raspberry-pi-bullseye-enable-legacy-camera-stack"></a>

**To enable the legacy camera stack**

    1. Run the following command to open the Raspberry Pi configuration tool.

       ```
       sudo raspi-config
       ```

    1. Select **Interface Options**.

    1. Select **Legacy camera** to enable the legacy camera stack.

    1. Reboot the Raspberry Pi.

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#dlr-object-detection-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

------
#### [ 2.1.13 and 2.1.14 ]

The following table lists the dependencies for version 2.1.13 and 2.1.14 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.13.0 | Soft | 
| [DLR object detection model store](dlr-object-detection-model-store-component.md) | \$12.1.0 | Hard | 
| [DLR](dlr-component.md) | \$11.6.0 | Hard | 

------
#### [ 2.1.12 ]

The following table lists the dependencies for version 2.1.12 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.12.0 | Soft | 
| [DLR object detection model store](dlr-object-detection-model-store-component.md) | \$12.1.0 | Hard | 
| [DLR](dlr-component.md) | \$11.6.0 | Hard | 

------
#### [ 2.1.11 ]

The following table lists the dependencies for version 2.1.11 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.11.0 | Soft | 
| [DLR object detection model store](dlr-object-detection-model-store-component.md) | \$12.1.0 | Hard | 
| [DLR](dlr-component.md) | \$11.6.0 | Hard | 

------
#### [ 2.1.10 ]

The following table lists the dependencies for version 2.1.10 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.10.0 | Soft | 
| [DLR object detection model store](dlr-object-detection-model-store-component.md) | \$12.1.0 | Hard | 
| [DLR](dlr-component.md) | \$11.6.0 | Hard | 

------
#### [ 2.1.9 ]

The following table lists the dependencies for version 2.1.9 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.9.0 | Soft | 
| [DLR object detection model store](dlr-object-detection-model-store-component.md) | \$12.1.0 | Hard | 
| [DLR](dlr-component.md) | \$11.6.0 | Hard | 

------
#### [ 2.1.8 ]

The following table lists the dependencies for version 2.1.8 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.8.0 | Soft | 
| [DLR object detection model store](dlr-object-detection-model-store-component.md) | \$12.1.0 | Hard | 
| [DLR](dlr-component.md) | \$11.6.0 | Hard | 

------
#### [ 2.1.7 ]

The following table lists the dependencies for version 2.1.7 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.7.0 | Soft | 
| [DLR object detection model store](dlr-object-detection-model-store-component.md) | \$12.1.0 | Hard | 
| [DLR](dlr-component.md) | \$11.6.0 | Hard | 

------
#### [ 2.1.6 ]

The following table lists the dependencies for version 2.1.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.6.0 | Soft | 
| [DLR object detection model store](dlr-object-detection-model-store-component.md) | \$12.1.0 | Hard | 
| [DLR](dlr-component.md) | \$11.6.0 | Hard | 

------
#### [ 2.1.4 - 2.1.5 ]

The following table lists the dependencies for versions 2.1.4 to 2.1.5 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.5.0 | Soft | 
| [DLR object detection model store](dlr-object-detection-model-store-component.md) | \$12.1.0 | Hard | 
| [DLR](dlr-component.md) | \$11.6.0 | Hard | 

------
#### [ 2.1.3 ]

The following table lists the dependencies for version 2.1.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.4.0 | Soft | 
| [DLR object detection model store](dlr-object-detection-model-store-component.md) | \$12.1.0 | Hard | 
| [DLR](dlr-component.md) | \$11.6.0 | Hard | 

------
#### [ 2.1.2 ]

The following table lists the dependencies for version 2.1.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.3.0 | Soft | 
| [DLR object detection model store](dlr-object-detection-model-store-component.md) | \$12.1.0 | Hard | 
| [DLR](dlr-component.md) | \$11.6.0 | Hard | 

------
#### [ 2.1.1 ]

The following table lists the dependencies for version 2.1.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.2.0 | Soft | 
| [DLR object detection model store](dlr-object-detection-model-store-component.md) | \$12.1.0 | Hard | 
| [DLR](dlr-component.md) | \$11.6.0 | Hard | 

------
#### [ 2.0.x ]

The following table lists the dependencies for version 2.0.x of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | \$12.0.0 | Soft | 
| DLR object detection model store | \$12.0.0 | Hard | 
| DLR | \$11.3.0 | Soft | 

------

## Configuration


This component provides the following configuration parameters that you can customize when you deploy the component.

------
#### [ 2.1.x ]

`accessControl`  
<a name="ml-config-accesscontrol-desc"></a>(Optional) The object that contains the [authorization policy](interprocess-communication.md#ipc-authorization-policies) that allows the component to publish messages to the default notifications topic.   
Default:   

```
{
   "aws.greengrass.ipc.mqttproxy": {
      "aws.greengrass.DLRObjectDetection:mqttproxy:1": {
         "policyDescription": "Allows access to publish via topic ml/dlr/object-detection.",
         "operations": [
            "aws.greengrass#PublishToIoTCore"
         ],
         "resources": [
            "ml/dlr/object-detection"
         ]
      }
   }
}
```

`PublishResultsOnTopic`  
<a name="ml-config-publishresultsontopic-desc"></a>(Optional) The topic on which you want to publish the inference results. If you modify this value, then you must also modify the value of `resources` in the `accessControl` parameter to match your custom topic name.  
Default: `ml/dlr/object-detection`

`Accelerator`  <a name="ml-config-accelerator"></a>
The accelerator that you want to use. Supported values are `cpu` and `gpu`.  
The sample models in the dependent model component support only CPU acceleration. To use GPU acceleration with a different custom model, [create a custom model component](ml-customization.md#override-public-model-store) to override the public model component.  
Default: `cpu`

`ImageDirectory`  
<a name="ml-config-imagedirectory-desc"></a>(Optional) The path of the folder on the device where inference components read images. You can modify this value to any location on your device to which you have read/write access.  
<a name="ml-config-imagedirectory-obj-default"></a>Default: `/greengrass/v2/packages/artifacts-unarchived/component-name/object_detection/sample_images/`  
If you set the value of `UseCamera` to `true`, then this configuration parameter is ignored. 

`ImageName`  
<a name="ml-config-imagename-desc"></a>(Optional) The name of the image that the inference component uses as an input to a make prediction. The component looks for the image in the folder specified in `ImageDirectory`. By default, the component uses the sample image in the default image directory. AWS IoT Greengrass supports the following image formats: `jpeg`, `jpg`, `png`, and `npy`.   
<a name="ml-config-imagename-obj-default"></a>Default: `objects.jpg`  
If you set the value of `UseCamera` to `true`, then this configuration parameter is ignored. 

`InferenceInterval`  <a name="ml-config-inferenceinterval"></a>
(Optional) The time in seconds between each prediction made by the inference code. The sample inference code runs indefinitely and repeats its predictions at the specified time interval. For example, you can change this to a shorter interval if you want to use images taken by a camera for real-time prediction.  
Default: `3600`

`ModelResourceKey`  <a name="ml-config-modelresourcekey"></a>
<a name="ml-config-modelresourcekey-desc"></a>(Optional) The models that are used in the dependent public model component. Modify this parameter only if you override the public model component with a custom component.   
Default:  

```
{
    "armv7l": "DLR-yolo3-armv7l-cpu-ObjectDetection",
    "aarch64": "DLR-yolo3-aarch64-gpu-ObjectDetection",
    "x86_64": "DLR-yolo3-x86_64-cpu-ObjectDetection",
    "windows": "DLR-resnet50-win-cpu-ObjectDetection"
}
```

`UseCamera`  <a name="ml-config-usecamera"></a>
(Optional) String value that defines whether to use images from a camera connected to the Greengrass core device. Supported values are `true` and `false`.  
When you set this value to `true`, the sample inference code accesses the camera on your device and runs inference locally on the captured image. The values of the `ImageName` and `ImageDirectory` parameters are ignored. Make sure that the user running this component has read/write access to the location where the camera stores captured images.  
Default: `false`  
When you view the recipe of this component, the `UseCamera` configuration parameter doesn't appear in the default configuration. However, you can modify the value of this parameter in a [configuration merge update](update-component-configurations.md) when you deploy the component.   
When you set `UseCamera` to `true`, you must also create a symlink to enable the inference component to access your camera from the virtual environment that is created by the runtime component. For more information about using a camera with the sample inference components, see [Update component configurations](ml-tutorial-image-classification-camera.md).

------
#### [ 2.0.x ]

`MLRootPath`  <a name="ml-config-mlrootpath"></a>
<a name="ml-config-mlrootpath-desc"></a>(Optional) The path of the folder on Linux core devices where inference components read images and write inference results. You can modify this value to any location on your device to which the user running this component has read/write access.  
<a name="ml-config-mlrootpath-default-dlr"></a>Default: `/greengrass/v2/work/variant.DLR/greengrass_ml`  
<a name="ml-config-mlrootpath-default-tfl"></a>Default: `/greengrass/v2/work/variant.TensorFlowLite/greengrass_ml`

`Accelerator`  
Do not modify. Currently, the only supported value for the accelerator is `cpu`, because the models in the dependent model components are compiled only for the CPU accelerator.

`ImageName`  
<a name="ml-config-imagename-desc-dlr-1.3.0"></a>(Optional) The name of the image that the inference component uses as an input to a make prediction. The component looks for the image in the folder specified in `ImageDirectory`. The default location is `MLRootPath/images`. AWS IoT Greengrass supports the following image formats: `jpeg`, `jpg`, `png`, and `npy`.   
<a name="ml-config-imagename-obj-default"></a>Default: `objects.jpg`

`InferenceInterval`  <a name="ml-config-inferenceinterval"></a>
(Optional) The time in seconds between each prediction made by the inference code. The sample inference code runs indefinitely and repeats its predictions at the specified time interval. For example, you can change this to a shorter interval if you want to use images taken by a camera for real-time prediction.  
Default: `3600`

`ModelResourceKey`  <a name="ml-config-modelresourcekey"></a>
<a name="ml-config-modelresourcekey-desc"></a>(Optional) The models that are used in the dependent public model component. Modify this parameter only if you override the public model component with a custom component.   
Default:  

```
{
    armv7l: "DLR-yolo3-armv7l-cpu-ObjectDetection",
    x86_64: "DLR-yolo3-x86_64-cpu-ObjectDetection"
}
```

------

## Local log file


This component uses the following log file.

------
#### [ Linux ]

```
/greengrass/v2/logs/aws.greengrass.DLRObjectDetection.log
```

------
#### [ Windows ]

```
C:\greengrass\v2\logs\aws.greengrass.DLRObjectDetection.log
```

------

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the path to the AWS IoT Greengrass root folder.

------
#### [ Linux ]

  ```
  sudo tail -f /greengrass/v2/logs/aws.greengrass.DLRObjectDetection.log
  ```

------
#### [ Windows (PowerShell) ]

  ```
  Get-Content C:\greengrass\v2\logs\aws.greengrass.DLRObjectDetection.log -Tail 10 -Wait
  ```

------

## Changelog


The following table describes the changes in each version of the component.


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.1.14  | Version updated for Greengrass nucleus 2.12.5 release. | 
|  2.1.13  | Version updated for Greengrass nucleus version 2.12.0 release. | 
|  2.1.12  | Version updated for Greengrass nucleus version 2.11.0 release. | 
|  2.1.11  | Version updated for Greengrass nucleus version 2.10.0 release. | 
|  2.1.10  | Version updated for Greengrass nucleus version 2.9.0 release. | 
|  2.1.9  | Version updated for Greengrass nucleus version 2.8.0 release. | 
|  2.1.8  |  Version updated for Greengrass nucleus version 2.7.0 release.  | 
|  2.1.7  |  Version updated for Greengrass nucleus version 2.6.0 release.  | 
|  2.1.6  |  Version updated for Greengrass nucleus version 2.5.0 release.  | 
|  2.1.5  |  Component released in all AWS Regions.  | 
|  2.1.4  |  Version updated for Greengrass nucleus version 2.4.0 release. This version isn't available in Europe (London) (`eu-west-2`).  | 
|  2.1.3  |  Version updated for Greengrass nucleus version 2.3.0 release.  | 
|  2.1.2  |  <a name="changelog-dlr-object-detection-2.1.2"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/dlr-object-detection-component.html)  | 
|  2.1.1  |  <a name="changelog-dlr-object-detection-2.1.1"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/dlr-object-detection-component.html)  | 
|  2.0.4  |  Initial version.  | 

# DLR image classification model store


The DLR image classification model store is a machine learning model component that contains pre-trained ResNet-50 models as Greengrass artifacts. The pre-trained models used in this component are fetched from the [GluonCV Model Zoo](https://cv.gluon.ai/model_zoo/index.html) and are compiled using SageMaker AI Neo [Deep Learning Runtime](https://github.com/neo-ai/neo-ai-dlr).

The [DLR image classification](dlr-image-classification-component.md) inference component uses this component as a dependency for the model source. To use a custom-trained DLR model, [create a custom version](ml-customization.md#override-public-model-store) of this model component, and include your custom model as a component artifact. You can use the recipe of this component as a template to create custom model components. 

**Note**  
The name of the DLR image classification model store component varies depending on its version. The component name for version 2.1.x and later versions is `variant.DLR.ImageClassification.ModelStore`. The component name for version 2.0.x is `variant.ImageClassification.ModelStore`.

**Topics**
+ [

## Versions
](#dlr-image-classification-model-store-component-versions)
+ [

## Type
](#dlr-image-classification-model-store-component-type)
+ [

## Operating system
](#dlr-image-classification-model-store-component-os-support)
+ [

## Requirements
](#dlr-image-classification-model-store-component-requirements)
+ [

## Dependencies
](#dlr-image-classification-model-store-component-dependencies)
+ [

## Configuration
](#dlr-image-classification-model-store-component-configuration)
+ [

## Local log file
](#dlr-image-classification-model-store-component-log-file)
+ [

## Changelog
](#dlr-image-classification-model-store-component-changelog)

## Versions


This component has the following versions:
+ 2.1.x (`variant.DLR.ImageClassification.ModelStore`) 
+ 2.0.x (`variant.ImageClassification.ModelStore`) 

## Type


<a name="public-component-type-generic"></a>This <a name="public-component-type-generic-phrase"></a>component is a generic component (`aws.greengrass.generic`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs the component's lifecycle scripts.

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on core devices that run the following operating systems:
+ Linux
+ Windows

## Requirements


This component has the following requirements:<a name="ml-component-requirements"></a>
+ On Greengrass core devices running Amazon Linux 2 or Ubuntu 18.04, [GNU C Library](https://www.gnu.org/software/libc/) (glibc) version 2.27 or later installed on the device.
+ On Armv7l devices, such as Raspberry Pi, dependencies for OpenCV-Python installed on the device. Run the following command to install the dependencies.

  ```
  sudo apt-get install libopenjp2-7 libilmbase23 libopenexr-dev libavcodec-dev libavformat-dev libswscale-dev libv4l-dev libgtk-3-0 libwebp-dev
  ```
+ Raspberry Pi devices that run Raspberry Pi OS Bullseye must meet the following requirements:
  + NumPy 1.22.4 or later installed on the device. Raspberry Pi OS Bullseye includes an earlier version of NumPy, so you can run the following command to upgrade NumPy on the device.

    ```
    pip3 install --upgrade numpy
    ```
  + The legacy camera stack enabled on the device. Raspberry Pi OS Bullseye includes a new camera stack that is enabled by default and isn't compatible, so you must enable the legacy camera stack.<a name="raspberry-pi-bullseye-enable-legacy-camera-stack"></a>

**To enable the legacy camera stack**

    1. Run the following command to open the Raspberry Pi configuration tool.

       ```
       sudo raspi-config
       ```

    1. Select **Interface Options**.

    1. Select **Legacy camera** to enable the legacy camera stack.

    1. Reboot the Raspberry Pi.

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#dlr-image-classification-model-store-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

------
#### [ 2.1.12 - 2.1.14 ]

The following table lists the dependencies for version 2.1.12 and 2.1.13 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.13.0 | Soft | 

------
#### [ 2.1.11 ]

The following table lists the dependencies for version 2.1.11 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.12.0 | Soft | 

------
#### [ 2.1.10 ]

The following table lists the dependencies for version 2.1.10 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.11.0 | Soft | 

------
#### [ 2.1.9 ]

The following table lists the dependencies for version 2.1.9 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.10.0 | Soft | 

------
#### [ 2.1.8 ]

The following table lists the dependencies for version 2.1.8 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.9.0 | Soft | 

------
#### [ 2.1.7 ]

The following table lists the dependencies for version 2.1.7 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.8.0 | Soft | 

------
#### [ 2.1.6 ]

The following table lists the dependencies for version 2.1.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.7.0 | Soft | 

------
#### [ 2.1.5 ]

The following table lists the dependencies for version 2.1.5 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.6.0 | Soft | 

------
#### [ 2.1.4 ]

The following table lists the dependencies for version 2.1.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.5.0 | Soft | 

------
#### [ 2.1.3 ]

The following table lists the dependencies for version 2.1.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.4.0 | Soft | 

------
#### [ 2.1.2 ]

The following table lists the dependencies for version 2.1.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.3.0 | Soft | 

------
#### [ 2.1.1 ]

The following table lists the dependencies for version 2.1.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.2.0 | Soft | 

------
#### [ 2.0.x ]

The following table lists the dependencies for version 2.0.x of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | \$12.0.0 | Soft | 

------

## Configuration


This component doesn't have any configuration parameters.

## Local log file


This component doesn't output logs.

## Changelog


The following table describes the changes in each version of the component.


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.1.13  | Version updated for Greengrass nucleus 2.12.5 release. | 
|  2.1.12  | Version updated for Greengrass nucleus version 2.12.0 release. | 
|  2.1.11  | Version updated for Greengrass nucleus version 2.11.0 release. | 
|  2.1.10  | Version updated for Greengrass nucleus version 2.10.0 release. | 
|  2.1.9  | Version updated for Greengrass nucleus version 2.9.0 release. | 
|  2.1.8  | Version updated for Greengrass nucleus version 2.8.0 release. | 
|  2.1.7  |  Version updated for Greengrass nucleus version 2.7.0 release.  | 
|  2.1.6  |  Version updated for Greengrass nucleus version 2.6.0 release.  | 
|  2.1.5  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/dlr-image-classification-model-store-component.html)  | 
|  2.1.4  |  Version updated for Greengrass nucleus version 2.4.0 release.  | 
|  2.1.3  |  Version updated for Greengrass nucleus version 2.3.0 release.  | 
|  2.1.2  |  Version updated for Greengrass nucleus version 2.2.0 release.  | 
|  2.1.1  |  <a name="changelog-dlr-image-classification-model-store-2.1.1"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/dlr-image-classification-model-store-component.html)  | 
|  2.0.4  |  Initial version.  | 

# DLR object detection model store


The DLR object detection model store is a machine learning model component that contains pre-trained YOLOv3 models as Greengrass artifacts. The sample models used in this component are fetched from the [GluonCV Model Zoo](https://cv.gluon.ai/model_zoo/index.html) and compiled using SageMaker AI Neo [Deep Learning Runtime](https://github.com/neo-ai/neo-ai-dlr).

The [DLR object detection](dlr-object-detection-component.md) inference component uses this component as a dependency for the model source. To use a custom-trained DLR model, [create a custom version](ml-customization.md#override-public-model-store) of this model component, and include your custom model as a component artifact. You can use the recipe of this component as a template to create custom model components. 

**Note**  
The name of the DLR object detection model store component varies depending on its version. The component name for version 2.1.x and later versions is `variant.DLR.ObjectDetection.ModelStore`. The component name for version 2.0.x is `variant.ObjectDetection.ModelStore`.

**Topics**
+ [

## Versions
](#dlr-object-detection-model-store-component-versions)
+ [

## Type
](#dlr-object-detection-model-store-component-type)
+ [

## Operating system
](#dlr-object-detection-model-store-component-os-support)
+ [

## Requirements
](#dlr-object-detection-model-store-component-requirements)
+ [

## Dependencies
](#dlr-object-detection-model-store-component-dependencies)
+ [

## Configuration
](#dlr-object-detection-model-store-component-configuration)
+ [

## Local log file
](#dlr-object-detection-model-store-component-log-file)
+ [

## Changelog
](#dlr-object-detection-model-store-component-changelog)

## Versions


This component has the following versions:
+ 2.1.x 
+ 2.0.x

## Type


<a name="public-component-type-generic"></a>This <a name="public-component-type-generic-phrase"></a>component is a generic component (`aws.greengrass.generic`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs the component's lifecycle scripts.

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on core devices that run the following operating systems:
+ Linux
+ Windows

## Requirements


This component has the following requirements:<a name="ml-component-requirements"></a>
+ On Greengrass core devices running Amazon Linux 2 or Ubuntu 18.04, [GNU C Library](https://www.gnu.org/software/libc/) (glibc) version 2.27 or later installed on the device.
+ On Armv7l devices, such as Raspberry Pi, dependencies for OpenCV-Python installed on the device. Run the following command to install the dependencies.

  ```
  sudo apt-get install libopenjp2-7 libilmbase23 libopenexr-dev libavcodec-dev libavformat-dev libswscale-dev libv4l-dev libgtk-3-0 libwebp-dev
  ```
+ Raspberry Pi devices that run Raspberry Pi OS Bullseye must meet the following requirements:
  + NumPy 1.22.4 or later installed on the device. Raspberry Pi OS Bullseye includes an earlier version of NumPy, so you can run the following command to upgrade NumPy on the device.

    ```
    pip3 install --upgrade numpy
    ```
  + The legacy camera stack enabled on the device. Raspberry Pi OS Bullseye includes a new camera stack that is enabled by default and isn't compatible, so you must enable the legacy camera stack.<a name="raspberry-pi-bullseye-enable-legacy-camera-stack"></a>

**To enable the legacy camera stack**

    1. Run the following command to open the Raspberry Pi configuration tool.

       ```
       sudo raspi-config
       ```

    1. Select **Interface Options**.

    1. Select **Legacy camera** to enable the legacy camera stack.

    1. Reboot the Raspberry Pi.

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#dlr-object-detection-model-store-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

------
#### [ 2.1.13 and 2.1.14 ]

The following table lists the dependencies for version 2.1.13 and 2.1.14 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.13.0 | Soft | 

------
#### [ 2.1.12 ]

The following table lists the dependencies for version 2.1.12 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.12.0 | Soft | 

------
#### [ 2.1.11 ]

The following table lists the dependencies for version 2.1.11 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.11.0 | Soft | 

------
#### [ 2.1.10 ]

The following table lists the dependencies for version 2.1.10 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.10.0 | Soft | 

------
#### [ 2.1.9 ]

The following table lists the dependencies for version 2.1.9 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.9.0 | Soft | 

------
#### [ 2.1.8 ]

The following table lists the dependencies for version 2.1.8 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.8.0 | Soft | 

------
#### [ 2.1.7 ]

The following table lists the dependencies for version 2.1.7 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.7.0 | Soft | 

------
#### [ 2.1.5 and 2.1.6 ]

The following table lists the dependencies for versions 2.1.5 and 2.1.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.6.0 | Soft | 

------
#### [ 2.1.4 ]

The following table lists the dependencies for version 2.1.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.5.0 | Soft | 

------
#### [ 2.1.3 ]

The following table lists the dependencies for version 2.1.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.4.0 | Soft | 

------
#### [ 2.1.2 ]

The following table lists the dependencies for version 2.1.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.3.0 | Soft | 

------
#### [ 2.1.1 ]

The following table lists the dependencies for version 2.1.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.2.0 | Soft | 

------
#### [ 2.0.x ]

The following table lists the dependencies for version 2.0.x of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | \$12.0.0 | Soft | 

------

## Configuration


This component doesn't have any configuration parameters.

## Local log file


This component doesn't output logs.

## Changelog


The following table describes the changes in each version of the component.


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.1.14  |  Version updated for Greengrass nucleus 2.12.5 release.  | 
|  2.1.13  | Version updated for Greengrass nucleus version 2.12.0 release. | 
|  2.1.12  | Version updated for Greengrass nucleus version 2.11.0 release. | 
|  2.1.11  | Version updated for Greengrass nucleus version 2.10.0 release. | 
|  2.1.10  | Version updated for Greengrass nucleus version 2.9.0 release. | 
|  2.1.9  | Version updated for Greengrass nucleus version 2.8.0 release. | 
|  2.1.8  |  Version updated for Greengrass nucleus version 2.7.0 release.  | 
|  2.1.7  |  Version updated for Greengrass nucleus version 2.6.0 release.  | 
|  2.1.6  |  Adds a CPU model to fix an issue on Armv8 (AArch64) devices.  | 
|  2.1.5  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/dlr-object-detection-model-store-component.html)  | 
|  2.1.4  |  Version updated for Greengrass nucleus version 2.4.0 release.  | 
|  2.1.3  |  Version updated for Greengrass nucleus version 2.3.0 release.  | 
|  2.1.2  |  Version updated for Greengrass nucleus version 2.2.0 release.  | 
|  2.1.1  |  <a name="changelog-dlr-object-detection-model-store-2.1.1"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/dlr-object-detection-model-store-component.html) | 
|  2.0.4  |  Initial version.  | 

# DLR runtime


The DLR runtime component (`variant.DLR`) contains a script that installs [Deep Learning Runtime](https://github.com/neo-ai/neo-ai-dlr) (DLR) and its dependencies in a virtual environment on your device. The [DLR image classification](dlr-image-classification-component.md) and [DLR object detection](dlr-object-detection-component.md) components use this component as a dependency for installing DLR. Component version 1.6.x installs DLR v1.6.0 and component version 1.3.x installs DLR v1.3.0. 

To use a different runtime, you can use the recipe of this component as a template to [create a custom machine learning component](ml-customization.md). 

**Topics**
+ [

## Versions
](#dlr-component-versions)
+ [

## Type
](#dlr-component-type)
+ [

## Operating system
](#dlr-component-os-support)
+ [

## Requirements
](#dlr-component-requirements)
+ [

## Dependencies
](#dlr-component-dependencies)
+ [

## Configuration
](#dlr-component-configuration)
+ [

## Usage
](#dlr-component-usage)
+ [

## Local log file
](#dlr-component-log-file)
+ [

## Changelog
](#dlr-component-changelog)

## Versions


This component has the following versions:
+ 1.6.x
+ 1.3.x

## Type


<a name="public-component-type-generic"></a>This <a name="public-component-type-generic-phrase"></a>component is a generic component (`aws.greengrass.generic`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs the component's lifecycle scripts.

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on core devices that run the following operating systems:
+ Linux
+ Windows

## Requirements


This component has the following requirements:<a name="ml-component-requirements"></a>
+ On Greengrass core devices running Amazon Linux 2 or Ubuntu 18.04, [GNU C Library](https://www.gnu.org/software/libc/) (glibc) version 2.27 or later installed on the device.
+ On Armv7l devices, such as Raspberry Pi, dependencies for OpenCV-Python installed on the device. Run the following command to install the dependencies.

  ```
  sudo apt-get install libopenjp2-7 libilmbase23 libopenexr-dev libavcodec-dev libavformat-dev libswscale-dev libv4l-dev libgtk-3-0 libwebp-dev
  ```
+ Raspberry Pi devices that run Raspberry Pi OS Bullseye must meet the following requirements:
  + NumPy 1.22.4 or later installed on the device. Raspberry Pi OS Bullseye includes an earlier version of NumPy, so you can run the following command to upgrade NumPy on the device.

    ```
    pip3 install --upgrade numpy
    ```
  + The legacy camera stack enabled on the device. Raspberry Pi OS Bullseye includes a new camera stack that is enabled by default and isn't compatible, so you must enable the legacy camera stack.<a name="raspberry-pi-bullseye-enable-legacy-camera-stack"></a>

**To enable the legacy camera stack**

    1. Run the following command to open the Raspberry Pi configuration tool.

       ```
       sudo raspi-config
       ```

    1. Select **Interface Options**.

    1. Select **Legacy camera** to enable the legacy camera stack.

    1. Reboot the Raspberry Pi.

### Endpoints and ports


By default, this component uses an installer script to install packages using the `apt`, `yum`, `brew`, and `pip` commands, depending on what platform the core device uses. This component must be able to perform outbound requests to various package indexes and repositories to run the installer script. To allow this component's outbound traffic through a proxy or firewall, you must identify the endpoints for the package indexes and repositories where your core device connects to install.

Consider the following when you identify endpoints required for this component's install script:
+ The endpoints depend on the core device's platform. For example, a core device that runs Ubuntu uses `apt` rather than `yum` or `brew`. Additionally, devices that use the same package index might have different source lists, so they might retrieve packages from different repositories.
+ The endpoints might differ between multiple devices that use the same package index, because each device has its own source lists that define where to retrieve packages.
+ The endpoints might change over time. Each package index provides the URLs of the repositories where you download packages, and the owner of a package can change what URLs the package index provides.

For more information about the dependencies that this component installs, and how to disable the installer script, see the [UseInstaller](#dlr-component-config-useinstaller-term) configuration parameter.

For more information about endpoints and ports required for basic operation, see [Allow device traffic through a proxy or firewall](allow-device-traffic.md).

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#dlr-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

------
#### [ 1.6.11 - 1.6.16 ]

The following table lists the dependencies for versions 1.6.11 to 1.6.16 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <3.0.0 | Soft | 

------
#### [ 1.6.10 ]

The following table lists the dependencies for version 1.6.10 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.9.0 | Soft | 

------
#### [ 1.6.9 ]

The following table lists the dependencies for version 1.6.9 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.8.0 | Soft | 

------
#### [ 1.6.8 ]

The following table lists the dependencies for version 1.6.8 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.7.0 | Soft | 

------
#### [ 1.6.6 and 1.6.7 ]

The following table lists the dependencies for versions 1.6.6 and 1.6.7 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.6.0 | Soft | 

------
#### [ 1.6.4 and 1.6.5 ]

The following table lists the dependencies for versions 1.6.4 and 1.6.5 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.5.0 | Soft | 

------
#### [ 1.6.3 ]

The following table lists the dependencies for version 1.6.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.4.0 | Soft | 

------
#### [ 1.6.2 ]

The following table lists the dependencies for version 1.6.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.3.0 | Soft | 

------
#### [ 1.6.1 ]

The following table lists the dependencies for version 1.6.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.2.0 | Soft | 

------
#### [ 1.3.x ]

The following table lists the dependencies for version 1.3.x of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | \$12.0.0 | Soft | 

------

For more information about component dependencies, see the [component recipe reference](component-recipe-reference.md#recipe-reference-component-dependencies).

## Configuration


This component provides the following configuration parameters that you can customize when you deploy the component.

`MLRootPath`  
<a name="ml-config-mlrootpath-desc"></a>(Optional) The path of the folder on Linux core devices where inference components read images and write inference results. You can modify this value to any location on your device to which the user running this component has read/write access.  
<a name="ml-config-mlrootpath-default-dlr"></a>Default: `/greengrass/v2/work/variant.DLR/greengrass_ml`

`WindowsMLRootPath`  
This feature is available in v1.6.6 and later of this component.  
<a name="ml-config-windowsmlrootpath-desc"></a>(Optional) The path of the folder on Windows core device where inference components read images and write inference results. You can modify this value to any location on your device to which the user running this component has read/write access.  
<a name="ml-config-windowsmlrootpath-default-dlr"></a>Default: `C:\greengrass\v2\\work\\variant.DLR\\greengrass_ml`

  `UseInstaller`   
<a name="ml-config-useinstaller-desc-dlr"></a>(Optional) String value that defines whether to use the installer script in this component to install DLR and its dependencies. Supported values are `true` and `false`.   <a name="ml-config-useinstaller-libraries-dlr"></a>

Set this value to `false` if you want to use a custom script for DLR installation, or if you want to include runtime dependencies in a pre-built Linux image. To use this component with the AWS-provided DLR inference components, install the following libraries, including any dependencies, and make them available to the system user, such as `ggc_user`, that runs the ML components.
+ [Python](https://www.python.org/downloads/) 3.7 or later, including `pip` for your version of Python.
+ [Deep Learning Runtime](https://github.com/neo-ai/neo-ai-dlr) v1.6.0
+ [NumPy](https://numpy.org/install/).
+ [OpenCV-Python](https://pypi.org/project/opencv-python/).
+ [AWS IoT Device SDK v2 for Python](https://github.com/aws/aws-iot-device-sdk-python-v2).
+ [AWS Common Runtime (CRT) Python](https://github.com/awslabs/aws-crt-python).
+ [Picamera](https://picamera.readthedocs.io/en/release-1.13/) (for Raspberry Pi devices only).
+ [`awscam` module](https://docs.aws.amazon.com/deeplens/latest/dg/deeplens-library-awscam-module.html) (for AWS DeepLens devices).
+ libGL (for Linux devices)
<a name="ml-config-useinstaller-default"></a>Default: `true`

## Usage


Use this component with the `UseInstaller` configuration parameter set to `true` to install DLR and its dependencies on your device. The component sets up a virtual environment on your device that includes the OpenCV and NumPy libraries that are required for DLR. 

**Note**  <a name="ml-installer-component-usage-note"></a>
The installer script in this component also installs the latest versions of additional system libraries that are required to configure the virtual environment on your device and to use the installed machine learning framework. This might upgrade the existing system libraries on your device. Review the following table for the list of libraries that this component installs for each supported operating system. If you want to customize this installation process, set the `UseInstaller` configuration parameter to `false`, and develop your own installer script.


| Platform | Libraries installed on the device system | Libraries installed in the virtual environment | 
| --- | --- | --- | 
| Armv7l | build-essential, cmake, ca-certificates, git | setuptools, wheel | 
| Amazon Linux 2 | mesa-libGL | None | 
| Ubuntu | wget | None | 

When you deploy your inference component, this runtime component first verifies if your device already has DLR and its dependencies installed, and if not, then it installs them for you. 

## Local log file


This component uses the following log file.

------
#### [ Linux ]

```
/greengrass/v2/logs/variant.DLR.log
```

------
#### [ Windows ]

```
C:\greengrass\v2\logs\variant.DLR.log
```

------

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the path to the AWS IoT Greengrass root folder.

------
#### [ Linux ]

  ```
  sudo tail -f /greengrass/v2/logs/variant.DLR.log
  ```

------
#### [ Windows (PowerShell) ]

  ```
  Get-Content C:\greengrass\v2\logs\variant.DLR.log -Tail 10 -Wait
  ```

------

## Changelog


The following table describes the changes in each version of the component.


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  1.6.16  |  Version updated for Greengrass nucleus version 2.12.5.  | 
|  1.6.12  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/dlr-component.html)  | 
|  1.6.11  | Version updated for Greengrass nucleus version 2.9.0 release. | 
|  1.6.10  | Version updated for Greengrass nucleus version 2.8.0 release. | 
|  1.6.9  |  Version updated for Greengrass nucleus version 2.7.0 release.  | 
|  1.6.8  |  Version updated for Greengrass nucleus version 2.6.0 release.  | 
|  1.6.7  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/dlr-component.html)  | 
|  1.6.6  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/dlr-component.html)  | 
|  1.6.5  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/dlr-component.html)  | 
|  1.6.4  |  Version updated for Greengrass nucleus version 2.4.0 release.  | 
|  1.6.3  |  Version updated for Greengrass nucleus version 2.3.0 release.  | 
|  1.6.2  |  Version updated for Greengrass nucleus version 2.2.0 release.  | 
|  1.6.1  |  <a name="changelog-dlr-1.6.1"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/dlr-component.html)  | 
|  1.3.2  |  Initial version. Installs DLR v1.3.0.  | 

# TensorFlow Lite image classification


The TensorFlow Lite image classification component (`aws.greengrass.TensorFlowLiteImageClassification`) contains sample inference code to perform image classification inference using the [TensorFlow Lite](https://www.tensorflow.org/lite/guide/python) runtime and a sample pre-trained MobileNet 1.0 quantized model. This component uses the variant [TensorFlow Lite image classification model store](tensorflow-lite-image-classification-model-store-component.md) and the [TensorFlow Lite runtime](tensorflow-lite-component.md) components as dependencies to download the TensorFlow Lite runtime and the sample model.

To use this inference component with a custom-trained TensorFlow Lite model, [create a custom version](ml-customization.md#override-public-model-store) of the dependent model store component. To use your own custom inference code, you can use the recipe of this component as a template to [create a custom inference component](ml-customization.md#create-inference-component).

**Topics**
+ [

## Versions
](#tensorflow-lite-image-classification-component-versions)
+ [

## Type
](#tensorflow-lite-image-classification-component-type)
+ [

## Operating system
](#tensorflow-lite-image-classification-component-os-support)
+ [

## Requirements
](#tensorflow-lite-image-classification-component-requirements)
+ [

## Dependencies
](#tensorflow-lite-image-classification-component-dependencies)
+ [

## Configuration
](#tensorflow-lite-image-classification-component-configuration)
+ [

## Local log file
](#tensorflow-lite-image-classification-component-log-file)
+ [

## Changelog
](#tensorflow-lite-image-classification-component-changelog)

## Versions


This component has the following versions:
+ 2.1.x

## Type


<a name="public-component-type-generic"></a>This <a name="public-component-type-generic-phrase"></a>component is a generic component (`aws.greengrass.generic`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs the component's lifecycle scripts.

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on core devices that run the following operating systems:
+ Linux
+ Windows

## Requirements


This component has the following requirements:<a name="ml-component-requirements"></a>
+ On Greengrass core devices running Amazon Linux 2 or Ubuntu 18.04, [GNU C Library](https://www.gnu.org/software/libc/) (glibc) version 2.27 or later installed on the device.
+ On Armv7l devices, such as Raspberry Pi, dependencies for OpenCV-Python installed on the device. Run the following command to install the dependencies.

  ```
  sudo apt-get install libopenjp2-7 libilmbase23 libopenexr-dev libavcodec-dev libavformat-dev libswscale-dev libv4l-dev libgtk-3-0 libwebp-dev
  ```
+ Raspberry Pi devices that run Raspberry Pi OS Bullseye must meet the following requirements:
  + NumPy 1.22.4 or later installed on the device. Raspberry Pi OS Bullseye includes an earlier version of NumPy, so you can run the following command to upgrade NumPy on the device.

    ```
    pip3 install --upgrade numpy
    ```
  + The legacy camera stack enabled on the device. Raspberry Pi OS Bullseye includes a new camera stack that is enabled by default and isn't compatible, so you must enable the legacy camera stack.<a name="raspberry-pi-bullseye-enable-legacy-camera-stack"></a>

**To enable the legacy camera stack**

    1. Run the following command to open the Raspberry Pi configuration tool.

       ```
       sudo raspi-config
       ```

    1. Select **Interface Options**.

    1. Select **Legacy camera** to enable the legacy camera stack.

    1. Reboot the Raspberry Pi.

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#tensorflow-lite-image-classification-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

------
#### [ 2.1.11 and 2.1.12 ]

The following table lists the dependencies for version 2.1.11 and 2.1.12 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.13.0 | Soft | 
| [TensorFlow Lite image classification model store](tensorflow-lite-image-classification-model-store-component.md) | >=2.1.0 <2.2.0 | Hard | 
| [TensorFlow Lite](tensorflow-lite-component.md) | >=2.5.0 <2.6.0 | Hard | 

------
#### [ 2.1.10 ]

The following table lists the dependencies for version 2.1.10 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.12.0 | Soft | 
| [TensorFlow Lite image classification model store](tensorflow-lite-image-classification-model-store-component.md) | >=2.1.0 <2.2.0 | Hard | 
| [TensorFlow Lite](tensorflow-lite-component.md) | >=2.5.0 <2.6.0 | Hard | 

------
#### [ 2.1.9 ]

The following table lists the dependencies for version 2.1.9 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.11.0 | Soft | 
| [TensorFlow Lite image classification model store](tensorflow-lite-image-classification-model-store-component.md) | >=2.1.0 <2.2.0 | Hard | 
| [TensorFlow Lite](tensorflow-lite-component.md) | >=2.5.0 <2.6.0 | Hard | 

------
#### [ 2.1.8 ]

The following table lists the dependencies for version 2.1.8 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.10.0 | Soft | 
| [TensorFlow Lite image classification model store](tensorflow-lite-image-classification-model-store-component.md) | >=2.1.0 <2.2.0 | Hard | 
| [TensorFlow Lite](tensorflow-lite-component.md) | >=2.5.0 <2.6.0 | Hard | 

------
#### [ 2.1.7 ]

The following table lists the dependencies for version 2.1.7 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.9.0 | Soft | 
| [TensorFlow Lite image classification model store](tensorflow-lite-image-classification-model-store-component.md) | >=2.1.0 <2.2.0 | Hard | 
| [TensorFlow Lite](tensorflow-lite-component.md) | >=2.5.0 <2.6.0 | Hard | 

------
#### [ 2.1.6 ]

The following table lists the dependencies for version 2.1.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.8.0 | Soft | 
| [TensorFlow Lite image classification model store](tensorflow-lite-image-classification-model-store-component.md) | >=2.1.0 <2.2.0 | Hard | 
| [TensorFlow Lite](tensorflow-lite-component.md) | >=2.5.0 <2.6.0 | Hard | 

------
#### [ 2.1.5 ]

The following table lists the dependencies for version 2.1.5 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.7.0 | Soft | 
| [TensorFlow Lite image classification model store](tensorflow-lite-image-classification-model-store-component.md) | >=2.1.0 <2.2.0 | Hard | 
| [TensorFlow Lite](tensorflow-lite-component.md) | >=2.5.0 <2.6.0 | Hard | 

------
#### [ 2.1.4 ]

The following table lists the dependencies for version 2.1.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.6.0 | Soft | 
| [TensorFlow Lite image classification model store](tensorflow-lite-image-classification-model-store-component.md) | >=2.1.0 <2.2.0 | Hard | 
| [TensorFlow Lite](tensorflow-lite-component.md) | >=2.5.0 <2.6.0 | Hard | 

------
#### [ 2.1.3 ]

The following table lists the dependencies for version 2.1.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.5.0 | Soft | 
| [TensorFlow Lite image classification model store](tensorflow-lite-image-classification-model-store-component.md) | >=2.1.0 <2.2.0 | Hard | 
| [TensorFlow Lite](tensorflow-lite-component.md) | >=2.5.0 <2.6.0 | Hard | 

------
#### [ 2.1.2 ]

The following table lists the dependencies for version 2.1.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.4.0 | Soft | 
| [TensorFlow Lite image classification model store](tensorflow-lite-image-classification-model-store-component.md) | >=2.1.0 <2.2.0 | Hard | 
| [TensorFlow Lite](tensorflow-lite-component.md) | >=2.5.0 <2.6.0 | Hard | 

------
#### [ 2.1.1 ]

The following table lists the dependencies for version 2.1.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.3.0 | Soft | 
| [TensorFlow Lite image classification model store](tensorflow-lite-image-classification-model-store-component.md) | >=2.1.0 <2.2.0 | Hard | 
| [TensorFlow Lite](tensorflow-lite-component.md) | >=2.5.0 <2.6.0 | Hard | 

------
#### [ 2.1.0 ]

The following table lists the dependencies for version 2.1.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.2.0 | Soft | 
| [TensorFlow Lite image classification model store](tensorflow-lite-image-classification-model-store-component.md) | >=2.1.0 <2.2.0 | Hard | 
| [TensorFlow Lite](tensorflow-lite-component.md) | >=2.5.0 <2.6.0 | Hard | 

------

## Configuration


This component provides the following configuration parameters that you can customize when you deploy the component.

`accessControl`  
<a name="ml-config-accesscontrol-desc"></a>(Optional) The object that contains the [authorization policy](interprocess-communication.md#ipc-authorization-policies) that allows the component to publish messages to the default notifications topic.   
Default:   

```
{
   "aws.greengrass.ipc.mqttproxy": {
      "aws.greengrass.TensorFlowLiteImageClassification:mqttproxy:1": {
         "policyDescription": "Allows access to publish via topic ml/tflite/image-classification.",
         "operations": [
            "aws.greengrass#PublishToIoTCore"
         ],
         "resources": [
            "ml/tflite/image-classification"
         ]
      }
   }
}
```

`PublishResultsOnTopic`  
<a name="ml-config-publishresultsontopic-desc"></a>(Optional) The topic on which you want to publish the inference results. If you modify this value, then you must also modify the value of `resources` in the `accessControl` parameter to match your custom topic name.  
Default: `ml/tflite/image-classification`

`Accelerator`  <a name="ml-config-accelerator"></a>
The accelerator that you want to use. Supported values are `cpu` and `gpu`.  
The sample models in the dependent model component support only CPU acceleration. To use GPU acceleration with a different custom model, [create a custom model component](ml-customization.md#override-public-model-store) to override the public model component.  
Default: `cpu`

`ImageDirectory`  
<a name="ml-config-imagedirectory-desc"></a>(Optional) The path of the folder on the device where inference components read images. You can modify this value to any location on your device to which you have read/write access.  
<a name="ml-config-imagedirectory-img-default"></a>Default: `/greengrass/v2/packages/artifacts-unarchived/component-name/image_classification/sample_images/`  
If you set the value of `UseCamera` to `true`, then this configuration parameter is ignored. 

`ImageName`  
<a name="ml-config-imagename-desc"></a>(Optional) The name of the image that the inference component uses as an input to a make prediction. The component looks for the image in the folder specified in `ImageDirectory`. By default, the component uses the sample image in the default image directory. AWS IoT Greengrass supports the following image formats: `jpeg`, `jpg`, `png`, and `npy`.   
<a name="ml-config-imagename-img-default"></a>Default: `cat.jpeg`  
If you set the value of `UseCamera` to `true`, then this configuration parameter is ignored. 

`InferenceInterval`  <a name="ml-config-inferenceinterval"></a>
(Optional) The time in seconds between each prediction made by the inference code. The sample inference code runs indefinitely and repeats its predictions at the specified time interval. For example, you can change this to a shorter interval if you want to use images taken by a camera for real-time prediction.  
Default: `3600`

`ModelResourceKey`  <a name="ml-config-modelresourcekey"></a>
<a name="ml-config-modelresourcekey-desc"></a>(Optional) The models that are used in the dependent public model component. Modify this parameter only if you override the public model component with a custom component.   
Default:  

```
{
    "model": "TensorFlowLite-Mobilenet"
}
```

`UseCamera`  <a name="ml-config-usecamera"></a>
(Optional) String value that defines whether to use images from a camera connected to the Greengrass core device. Supported values are `true` and `false`.  
When you set this value to `true`, the sample inference code accesses the camera on your device and runs inference locally on the captured image. The values of the `ImageName` and `ImageDirectory` parameters are ignored. Make sure that the user running this component has read/write access to the location where the camera stores captured images.  
Default: `false`  
When you view the recipe of this component, the `UseCamera` configuration parameter doesn't appear in the default configuration. However, you can modify the value of this parameter in a [configuration merge update](update-component-configurations.md) when you deploy the component.   
When you set `UseCamera` to `true`, you must also create a symlink to enable the inference component to access your camera from the virtual environment that is created by the runtime component. For more information about using a camera with the sample inference components, see [Update component configurations](ml-tutorial-image-classification-camera.md).

## Local log file


This component uses the following log file.

------
#### [ Linux ]

```
/greengrass/v2/logs/aws.greengrass.TensorFlowLiteImageClassification.log
```

------
#### [ Windows ]

```
C:\greengrass\v2\logs\aws.greengrass.TensorFlowLiteImageClassification.log
```

------

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the path to the AWS IoT Greengrass root folder.

------
#### [ Linux ]

  ```
  sudo tail -f /greengrass/v2/logs/aws.greengrass.TensorFlowLiteImageClassification.log
  ```

------
#### [ Windows (PowerShell) ]

  ```
  Get-Content C:\greengrass\v2\logs\aws.greengrass.TensorFlowLiteImageClassification.log -Tail 10 -Wait
  ```

------

## Changelog


The following table describes the changes in each version of the component.


|  Version  |  Changes  | 
| --- | --- | 
|  2.1.12  |  Version updated for Greengrass nucleus 2.12.5 release.  | 
|  2.1.11  | Version updated for Greengrass nucleus version 2.12.0 release. | 
|  2.1.10  | Version updated for Greengrass nucleus version 2.11.0 release. | 
|  2.1.9  | Version updated for Greengrass nucleus version 2.10.0 release. | 
|  2.1.8  | Version updated for Greengrass nucleus version 2.9.0 release. | 
|  2.1.7  | Version updated for Greengrass nucleus version 2.8.0 release. | 
|  2.1.6  |  Version updated for Greengrass nucleus version 2.7.0 release.  | 
|  2.1.5  |  Version updated for Greengrass nucleus version 2.6.0 release.  | 
|  2.1.4  |  Version updated for Greengrass nucleus version 2.5.0 release.  | 
|  2.1.3  |  Version updated for Greengrass nucleus version 2.4.0 release.  | 
|  2.1.2  |  Version updated for Greengrass nucleus version 2.3.0 release.  | 
|  2.1.1  |  Version updated for Greengrass nucleus version 2.2.0 release.  | 
|  2.1.0  |  Initial version.  | 

# TensorFlow Lite object detection


The TensorFlow Lite object detection component (`aws.greengrass.TensorFlowLiteObjectDetection`) contains sample inference code to perform object detection inference using [TensorFlow Lite](https://www.tensorflow.org/lite/guide/python) and a sample pre-trained Single Shot Detection (SSD) MobileNet 1.0 model. This component uses the variant [TensorFlow Lite object detection model store](tensorflow-lite-object-detection-model-store-component.md) and the [TensorFlow Lite runtime](tensorflow-lite-component.md) components as dependencies to download TensorFlow Lite and the sample model. 

To use this inference component with a custom-trained TensorFlow Lite model, you can [create a custom version](ml-customization.md#override-public-model-store) of the dependent model store component. To use your own custom inference code, use the recipe of this component as a template to [create a custom inference component](ml-customization.md#create-inference-component).

**Topics**
+ [

## Versions
](#tensorflow-lite-object-detection-component-versions)
+ [

## Type
](#tensorflow-lite-object-detection-component-type)
+ [

## Operating system
](#tensorflow-lite-object-detection-component-os-support)
+ [

## Requirements
](#tensorflow-lite-object-detection-component-requirements)
+ [

## Dependencies
](#tensorflow-lite-object-detection-component-dependencies)
+ [

## Configuration
](#tensorflow-lite-object-detection-component-configuration)
+ [

## Local log file
](#tensorflow-lite-object-detection-component-log-file)
+ [

## Changelog
](#tensorflow-lite-object-detection-component-changelog)

## Versions


This component has the following versions:
+ 2.1.x

## Type


<a name="public-component-type-generic"></a>This <a name="public-component-type-generic-phrase"></a>component is a generic component (`aws.greengrass.generic`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs the component's lifecycle scripts.

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on core devices that run the following operating systems:
+ Linux
+ Windows

## Requirements


This component has the following requirements:<a name="ml-component-requirements"></a>
+ On Greengrass core devices running Amazon Linux 2 or Ubuntu 18.04, [GNU C Library](https://www.gnu.org/software/libc/) (glibc) version 2.27 or later installed on the device.
+ On Armv7l devices, such as Raspberry Pi, dependencies for OpenCV-Python installed on the device. Run the following command to install the dependencies.

  ```
  sudo apt-get install libopenjp2-7 libilmbase23 libopenexr-dev libavcodec-dev libavformat-dev libswscale-dev libv4l-dev libgtk-3-0 libwebp-dev
  ```
+ Raspberry Pi devices that run Raspberry Pi OS Bullseye must meet the following requirements:
  + NumPy 1.22.4 or later installed on the device. Raspberry Pi OS Bullseye includes an earlier version of NumPy, so you can run the following command to upgrade NumPy on the device.

    ```
    pip3 install --upgrade numpy
    ```
  + The legacy camera stack enabled on the device. Raspberry Pi OS Bullseye includes a new camera stack that is enabled by default and isn't compatible, so you must enable the legacy camera stack.<a name="raspberry-pi-bullseye-enable-legacy-camera-stack"></a>

**To enable the legacy camera stack**

    1. Run the following command to open the Raspberry Pi configuration tool.

       ```
       sudo raspi-config
       ```

    1. Select **Interface Options**.

    1. Select **Legacy camera** to enable the legacy camera stack.

    1. Reboot the Raspberry Pi.

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#tensorflow-lite-object-detection-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

------
#### [ 2.1.11 and 2.1.12 ]

The following table lists the dependencies for version 2.1.11 and 2.1.12 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.13.0 | Soft | 
| [TensorFlow Lite image classification model store](tensorflow-lite-image-classification-model-store-component.md) | >=2.1.0 <2.2.0 | Hard | 
| [TensorFlow Lite](tensorflow-lite-component.md) | >=2.5.0 <2.6.0 | Hard | 

------
#### [ 2.1.10 ]

The following table lists the dependencies for version 2.1.10 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.12.0 | Soft | 
| [TensorFlow Lite image classification model store](tensorflow-lite-image-classification-model-store-component.md) | >=2.1.0 <2.2.0 | Hard | 
| [TensorFlow Lite](tensorflow-lite-component.md) | >=2.5.0 <2.6.0 | Hard | 

------
#### [ 2.1.9 ]

The following table lists the dependencies for version 2.1.9 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.11.0 | Soft | 
| [TensorFlow Lite image classification model store](tensorflow-lite-image-classification-model-store-component.md) | >=2.1.0 <2.2.0 | Hard | 
| [TensorFlow Lite](tensorflow-lite-component.md) | >=2.5.0 <2.6.0 | Hard | 

------
#### [ 2.1.8 ]

The following table lists the dependencies for version 2.1.8 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.10.0 | Soft | 
| [TensorFlow Lite image classification model store](tensorflow-lite-image-classification-model-store-component.md) | >=2.1.0 <2.2.0 | Hard | 
| [TensorFlow Lite](tensorflow-lite-component.md) | >=2.5.0 <2.6.0 | Hard | 

------
#### [ 2.1.7 ]

The following table lists the dependencies for version 2.1.7 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.9.0 | Soft | 
| [TensorFlow Lite image classification model store](tensorflow-lite-image-classification-model-store-component.md) | >=2.1.0 <2.2.0 | Hard | 
| [TensorFlow Lite](tensorflow-lite-component.md) | >=2.5.0 <2.6.0 | Hard | 

------
#### [ 2.1.6 ]

The following table lists the dependencies for version 2.1.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.8.0 | Soft | 
| [TensorFlow Lite image classification model store](tensorflow-lite-image-classification-model-store-component.md) | >=2.1.0 <2.2.0 | Hard | 
| [TensorFlow Lite](tensorflow-lite-component.md) | >=2.5.0 <2.6.0 | Hard | 

------
#### [ 2.1.5 ]

The following table lists the dependencies for version 2.1.5 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.7.0 | Soft | 
| [TensorFlow Lite image classification model store](tensorflow-lite-image-classification-model-store-component.md) | >=2.1.0 <2.2.0 | Hard | 
| [TensorFlow Lite](tensorflow-lite-component.md) | >=2.5.0 <2.6.0 | Hard | 

------
#### [ 2.1.4 ]

The following table lists the dependencies for version 2.1.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.6.0 | Soft | 
| [TensorFlow Lite image classification model store](tensorflow-lite-image-classification-model-store-component.md) | >=2.1.0 <2.2.0 | Hard | 
| [TensorFlow Lite](tensorflow-lite-component.md) | >=2.5.0 <2.6.0 | Hard | 

------
#### [ 2.1.3 ]

The following table lists the dependencies for version 2.1.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.5.0 | Soft | 
| [TensorFlow Lite image classification model store](tensorflow-lite-image-classification-model-store-component.md) | >=2.1.0 <2.2.0 | Hard | 
| [TensorFlow Lite](tensorflow-lite-component.md) | >=2.5.0 <2.6.0 | Hard | 

------
#### [ 2.1.2 ]

The following table lists the dependencies for version 2.1.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.4.0 | Soft | 
| [TensorFlow Lite image classification model store](tensorflow-lite-image-classification-model-store-component.md) | >=2.1.0 <2.2.0 | Hard | 
| [TensorFlow Lite](tensorflow-lite-component.md) | >=2.5.0 <2.6.0 | Hard | 

------
#### [ 2.1.1 ]

The following table lists the dependencies for version 2.1.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.3.0 | Soft | 
| [TensorFlow Lite image classification model store](tensorflow-lite-image-classification-model-store-component.md) | >=2.1.0 <2.2.0 | Hard | 
| [TensorFlow Lite](tensorflow-lite-component.md) | >=2.5.0 <2.6.0 | Hard | 

------
#### [ 2.1.0 ]

The following table lists the dependencies for version 2.1.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.2.0 | Soft | 
| [TensorFlow Lite image classification model store](tensorflow-lite-image-classification-model-store-component.md) | >=2.1.0 <2.2.0 | Hard | 
| [TensorFlow Lite](tensorflow-lite-component.md) | >=2.5.0 <2.6.0 | Hard | 

------

## Configuration


This component provides the following configuration parameters that you can customize when you deploy the component.

`accessControl`  
<a name="ml-config-accesscontrol-desc"></a>(Optional) The object that contains the [authorization policy](interprocess-communication.md#ipc-authorization-policies) that allows the component to publish messages to the default notifications topic.   
Default:   

```
{
   "aws.greengrass.ipc.mqttproxy": {
      "aws.greengrass.TensorFlowLiteObjectDetection:mqttproxy:1": {
         "policyDescription": "Allows access to publish via topic ml/tflite/object-detection.",
         "operations": [
            "aws.greengrass#PublishToIoTCore"
         ],
         "resources": [
            "ml/tflite/object-detection"
         ]
      }
   }
}
```

`PublishResultsOnTopic`  
<a name="ml-config-publishresultsontopic-desc"></a>(Optional) The topic on which you want to publish the inference results. If you modify this value, then you must also modify the value of `resources` in the `accessControl` parameter to match your custom topic name.  
Default: `ml/tflite/object-detection`

`Accelerator`  <a name="ml-config-accelerator"></a>
The accelerator that you want to use. Supported values are `cpu` and `gpu`.  
The sample models in the dependent model component support only CPU acceleration. To use GPU acceleration with a different custom model, [create a custom model component](ml-customization.md#override-public-model-store) to override the public model component.  
Default: `cpu`

`ImageDirectory`  
<a name="ml-config-imagedirectory-desc"></a>(Optional) The path of the folder on the device where inference components read images. You can modify this value to any location on your device to which you have read/write access.  
<a name="ml-config-imagedirectory-obj-default"></a>Default: `/greengrass/v2/packages/artifacts-unarchived/component-name/object_detection/sample_images/`  
If you set the value of `UseCamera` to `true`, then this configuration parameter is ignored. 

`ImageName`  
<a name="ml-config-imagename-desc"></a>(Optional) The name of the image that the inference component uses as an input to a make prediction. The component looks for the image in the folder specified in `ImageDirectory`. By default, the component uses the sample image in the default image directory. AWS IoT Greengrass supports the following image formats: `jpeg`, `jpg`, `png`, and `npy`.   
<a name="ml-config-imagename-obj-default"></a>Default: `objects.jpg`  
If you set the value of `UseCamera` to `true`, then this configuration parameter is ignored. 

`InferenceInterval`  <a name="ml-config-inferenceinterval"></a>
(Optional) The time in seconds between each prediction made by the inference code. The sample inference code runs indefinitely and repeats its predictions at the specified time interval. For example, you can change this to a shorter interval if you want to use images taken by a camera for real-time prediction.  
Default: `3600`

`ModelResourceKey`  <a name="ml-config-modelresourcekey"></a>
<a name="ml-config-modelresourcekey-desc"></a>(Optional) The models that are used in the dependent public model component. Modify this parameter only if you override the public model component with a custom component.   
Default:  

```
{
    "model": "TensorFlowLite-SSD"
}
```

`UseCamera`  <a name="ml-config-usecamera"></a>
(Optional) String value that defines whether to use images from a camera connected to the Greengrass core device. Supported values are `true` and `false`.  
When you set this value to `true`, the sample inference code accesses the camera on your device and runs inference locally on the captured image. The values of the `ImageName` and `ImageDirectory` parameters are ignored. Make sure that the user running this component has read/write access to the location where the camera stores captured images.  
Default: `false`  
When you view the recipe of this component, the `UseCamera` configuration parameter doesn't appear in the default configuration. However, you can modify the value of this parameter in a [configuration merge update](update-component-configurations.md) when you deploy the component.   
When you set `UseCamera` to `true`, you must also create a symlink to enable the inference component to access your camera from the virtual environment that is created by the runtime component. For more information about using a camera with the sample inference components, see [Update component configurations](ml-tutorial-image-classification-camera.md).

**Note**  <a name="ml-config-not-visible-note"></a>
When you view the recipe of this component, the `UseCamera` configuration parameter doesn't appear in the default configuration. However, you can modify the value of this parameter in a [configuration merge update](update-component-configurations.md) when you deploy the component.   
When you set `UseCamera` to `true`, you must also create a symlink to enable the inference component to access your camera from the virtual environment that is created by the runtime component. For more information about using a camera with the sample inference components, see [Update component configurations](ml-tutorial-image-classification-camera.md).

## Local log file


This component uses the following log file.

------
#### [ Linux ]

```
/greengrass/v2/logs/aws.greengrass.TensorFlowLiteObjectDetection.log
```

------
#### [ Windows ]

```
C:\greengrass\v2\logs\aws.greengrass.TensorFlowLiteObjectDetection.log
```

------

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the path to the AWS IoT Greengrass root folder.

------
#### [ Linux ]

  ```
  sudo tail -f /greengrass/v2/logs/aws.greengrass.TensorFlowLiteObjectDetection.log
  ```

------
#### [ Windows (PowerShell) ]

  ```
  Get-Content C:\greengrass\v2\logs\aws.greengrass.TensorFlowLiteObjectDetection.log -Tail 10 -Wait
  ```

------

## Changelog


The following table describes the changes in each version of the component.


|  Version  |  Changes  | 
| --- | --- | 
|  2.1.12  |  Version updated for Greengrass nucleus 2.12.5 release.  | 
|  2.1.11  | Version updated for Greengrass nucleus version 2.12.0 release. | 
|  2.1.10  | Version updated for Greengrass nucleus version 2.11.0 release. | 
|  2.1.9  | Version updated for Greengrass nucleus version 2.10.0 release. | 
|  2.1.8  | Version updated for Greengrass nucleus version 2.9.0 release. | 
|  2.1.7  | Version updated for Greengrass nucleus version 2.8.0 release. | 
|  2.1.6  |  Version updated for Greengrass nucleus version 2.7.0 release.  | 
|  2.1.5  |  Version updated for Greengrass nucleus version 2.6.0 release.  | 
|  2.1.4  |  Version updated for Greengrass nucleus version 2.5.0 release.  | 
|  2.1.3  |  Version updated for Greengrass nucleus version 2.4.0 release.  | 
|  2.1.2  |  Version updated for Greengrass nucleus version 2.3.0 release.  | 
|  2.1.1  |  <a name="changelog-tensorflow-lite-object-detection-2.1.1"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/tensorflow-lite-object-detection-component.html)  | 
|  2.1.0  |  Initial version.  | 

# TensorFlow Lite image classification model store


The TensorFlow Lite image classification model store (`variant.TensorFlowLite.ImageClassification.ModelStore`) is a machine learning model component that contains a pre-trained MobileNet v1 model as a Greengrass artifact. The sample model used in this component is fetched from the [TensorFlow Hub](https://tfhub.dev/) and implemented using [TensorFlow Lite](https://www.tensorflow.org/lite/guide/python).

The [TensorFlow Lite image classification](tensorflow-lite-image-classification-component.md) inference component uses this component as a dependency for the model source. To use a custom-trained TensorFlow Lite model, [create a custom version](ml-customization.md#override-public-model-store) of this model component, and include your custom model as a component artifact. You can use the recipe of this component as a template to create custom model components. 

**Topics**
+ [

## Versions
](#tensorflow-lite-image-classification-model-store-component-versions)
+ [

## Type
](#tensorflow-lite-image-classification-model-store-component-type)
+ [

## Operating system
](#tensorflow-lite-image-classification-model-store-component-os-support)
+ [

## Requirements
](#tensorflow-lite-image-classification-model-store-component-requirements)
+ [

## Dependencies
](#tensorflow-lite-image-classification-model-store-component-dependencies)
+ [

## Configuration
](#tensorflow-lite-image-classification-model-store-component-configuration)
+ [

## Local log file
](#tensorflow-lite-image-classification-model-store-component-log-file)
+ [

## Changelog
](#tensorflow-lite-image-classification-model-store-component-changelog)

## Versions


This component has the following versions:
+ 2.1.x

## Type


<a name="public-component-type-generic"></a>This <a name="public-component-type-generic-phrase"></a>component is a generic component (`aws.greengrass.generic`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs the component's lifecycle scripts.

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on core devices that run the following operating systems:
+ Linux
+ Windows

## Requirements


This component has the following requirements:<a name="ml-component-requirements"></a>
+ On Greengrass core devices running Amazon Linux 2 or Ubuntu 18.04, [GNU C Library](https://www.gnu.org/software/libc/) (glibc) version 2.27 or later installed on the device.
+ On Armv7l devices, such as Raspberry Pi, dependencies for OpenCV-Python installed on the device. Run the following command to install the dependencies.

  ```
  sudo apt-get install libopenjp2-7 libilmbase23 libopenexr-dev libavcodec-dev libavformat-dev libswscale-dev libv4l-dev libgtk-3-0 libwebp-dev
  ```
+ Raspberry Pi devices that run Raspberry Pi OS Bullseye must meet the following requirements:
  + NumPy 1.22.4 or later installed on the device. Raspberry Pi OS Bullseye includes an earlier version of NumPy, so you can run the following command to upgrade NumPy on the device.

    ```
    pip3 install --upgrade numpy
    ```
  + The legacy camera stack enabled on the device. Raspberry Pi OS Bullseye includes a new camera stack that is enabled by default and isn't compatible, so you must enable the legacy camera stack.<a name="raspberry-pi-bullseye-enable-legacy-camera-stack"></a>

**To enable the legacy camera stack**

    1. Run the following command to open the Raspberry Pi configuration tool.

       ```
       sudo raspi-config
       ```

    1. Select **Interface Options**.

    1. Select **Legacy camera** to enable the legacy camera stack.

    1. Reboot the Raspberry Pi.

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#tensorflow-lite-image-classification-model-store-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

------
#### [ 2.1.11 and 2.1.12  ]

The following table lists the dependencies for version 2.1.11 and 2.1.12 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.13.0 | Soft | 

------
#### [ 2.1.10 ]

The following table lists the dependencies for version 2.1.10 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.12.0 | Soft | 

------
#### [ 2.1.9 ]

The following table lists the dependencies for version 2.1.9 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.11.0 | Soft | 

------
#### [ 2.1.8 ]

The following table lists the dependencies for version 2.1.8 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.10.0 | Soft | 

------
#### [ 2.1.7 ]

The following table lists the dependencies for version 2.1.7 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.9.0 | Soft | 

------
#### [ 2.1.6 ]

The following table lists the dependencies for version 2.1.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.8.0 | Soft | 

------
#### [ 2.1.5 ]

The following table lists the dependencies for version 2.1.5 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.7.0 | Soft | 

------
#### [ 2.1.4 ]

The following table lists the dependencies for version 2.1.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.6.0 | Soft | 

------
#### [ 2.1.3 ]

The following table lists the dependencies for version 2.1.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.5.0 | Soft | 

------
#### [ 2.1.2 ]

The following table lists the dependencies for version 2.1.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.4.0 | Soft | 

------
#### [ 2.1.1 ]

The following table lists the dependencies for version 2.1.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.3.0 | Soft | 

------
#### [ 2.1.0 ]

The following table lists the dependencies for version 2.1.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.2.0 | Soft | 

------

## Configuration


This component doesn't have any configuration parameters.

## Local log file


This component doesn't output logs.

## Changelog


The following table describes the changes in each version of the component.


|  Version  |  Changes  | 
| --- | --- | 
|  2.1.12  |  Version updated for Greengrass nucleus 2.12.5 release.  | 
|  2.1.11  | Version updated for Greengrass nucleus version 2.12.0 release. | 
|  2.1.10  | Version updated for Greengrass nucleus version 2.11.0 release. | 
|  2.1.9  | Version updated for Greengrass nucleus version 2.10.0 release. | 
|  2.1.8  | Version updated for Greengrass nucleus version 2.9.0 release. | 
|  2.1.7  | Version updated for Greengrass nucleus version 2.8.0 release. | 
|  2.1.6  |  Version updated for Greengrass nucleus version 2.7.0 release.  | 
|  2.1.5  |  Version updated for Greengrass nucleus version 2.6.0 release.  | 
|  2.1.4  |  Version updated for Greengrass nucleus version 2.5.0 release.  | 
|  2.1.3  |  Version updated for Greengrass nucleus version 2.4.0 release.  | 
|  2.1.2  |  Version updated for Greengrass nucleus version 2.3.0 release.  | 
|  2.1.1  |  Version updated for Greengrass nucleus version 2.2.0 release.  | 
|  2.1.0  |  Initial version.  | 

# TensorFlow Lite object detection model store


The TensorFlow Lite object detection model store (`variant.TensorFlowLite.ObjectDetection.ModelStore`) is a machine learning model component that contains a pre-trained Single Shot Detection (SSD) MobileNet model as a Greengrass artifact. The sample model used in this component is fetched from the [TensorFlow Hub](https://tfhub.dev/) and implemented using [TensorFlow Lite](https://www.tensorflow.org/lite/guide/python).

The [TensorFlow Lite object detection](tensorflow-lite-object-detection-component.md) inference component uses this component as a dependency for the model source. To use a custom-trained TensorFlow Lite model, [create a custom version](ml-customization.md#override-public-model-store) of this model component, and include your custom model as a component artifact. You can use the recipe of this component as a template to create custom model components. 

**Topics**
+ [

## Versions
](#tensorflow-lite-object-detection-model-store-component-versions)
+ [

## Type
](#tensorflow-lite-object-detection-model-store-component-type)
+ [

## Operating system
](#tensorflow-lite-object-detection-model-store-component-os-support)
+ [

## Requirements
](#tensorflow-lite-object-detection-model-store-component-requirements)
+ [

## Dependencies
](#tensorflow-lite-object-detection-model-store-component-dependencies)
+ [

## Configuration
](#tensorflow-lite-object-detection-model-store-component-configuration)
+ [

## Local log file
](#tensorflow-lite-object-detection-model-store-component-log-file)
+ [

## Changelog
](#tensorflow-lite-object-detection-model-store-component-changelog)

## Versions


This component has the following versions:
+ 2.1.x

## Type


<a name="public-component-type-generic"></a>This <a name="public-component-type-generic-phrase"></a>component is a generic component (`aws.greengrass.generic`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs the component's lifecycle scripts.

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on core devices that run the following operating systems:
+ Linux
+ Windows

## Requirements


This component has the following requirements:<a name="ml-component-requirements"></a>
+ On Greengrass core devices running Amazon Linux 2 or Ubuntu 18.04, [GNU C Library](https://www.gnu.org/software/libc/) (glibc) version 2.27 or later installed on the device.
+ On Armv7l devices, such as Raspberry Pi, dependencies for OpenCV-Python installed on the device. Run the following command to install the dependencies.

  ```
  sudo apt-get install libopenjp2-7 libilmbase23 libopenexr-dev libavcodec-dev libavformat-dev libswscale-dev libv4l-dev libgtk-3-0 libwebp-dev
  ```
+ Raspberry Pi devices that run Raspberry Pi OS Bullseye must meet the following requirements:
  + NumPy 1.22.4 or later installed on the device. Raspberry Pi OS Bullseye includes an earlier version of NumPy, so you can run the following command to upgrade NumPy on the device.

    ```
    pip3 install --upgrade numpy
    ```
  + The legacy camera stack enabled on the device. Raspberry Pi OS Bullseye includes a new camera stack that is enabled by default and isn't compatible, so you must enable the legacy camera stack.<a name="raspberry-pi-bullseye-enable-legacy-camera-stack"></a>

**To enable the legacy camera stack**

    1. Run the following command to open the Raspberry Pi configuration tool.

       ```
       sudo raspi-config
       ```

    1. Select **Interface Options**.

    1. Select **Legacy camera** to enable the legacy camera stack.

    1. Reboot the Raspberry Pi.

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#tensorflow-lite-object-detection-model-store-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

------
#### [ 2.1.11 and 2.1.12 ]

The following table lists the dependencies for version 2.1.11 and 2.1.12 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.13.0 | Soft | 

------
#### [ 2.1.10 ]

The following table lists the dependencies for version 2.1.10 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.12.0 | Soft | 

------
#### [ 2.1.9 ]

The following table lists the dependencies for version 2.1.9 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.11.0 | Soft | 

------
#### [ 2.1.8 ]

The following table lists the dependencies for version 2.1.8 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.10.0 | Soft | 

------
#### [ 2.1.7 ]

The following table lists the dependencies for version 2.1.7 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.9.0 | Soft | 

------
#### [ 2.1.6 ]

The following table lists the dependencies for version 2.1.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.8.0 | Soft | 

------
#### [ 2.1.5 ]

The following table lists the dependencies for version 2.1.5 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.7.0 | Soft | 

------
#### [ 2.1.4 ]

The following table lists the dependencies for version 2.1.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.6.0 | Soft | 

------
#### [ 2.1.3 ]

The following table lists the dependencies for version 2.1.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.5.0 | Soft | 

------
#### [ 2.1.2 ]

The following table lists the dependencies for version 2.1.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.4.0 | Soft | 

------
#### [ 2.1.1 ]

The following table lists the dependencies for version 2.1.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.3.0 | Soft | 

------
#### [ 2.1.0 ]

The following table lists the dependencies for version 2.1.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.2.0 | Soft | 

------

## Configuration


This component doesn't have any configuration parameters.

## Local log file


This component doesn't output logs.

## Changelog


The following table describes the changes in each version of the component.


|  Version  |  Changes  | 
| --- | --- | 
|  2.1.12  |  Version updated for Greengrass nucleus 2.12.5 release.  | 
|  2.1.11  | Version updated for Greengrass nucleus version 2.12.0 release. | 
|  2.1.10  | Version updated for Greengrass nucleus version 2.11.0 release. | 
|  2.1.9  | Version updated for Greengrass nucleus version 2.10.0 release. | 
|  2.1.8  | Version updated for Greengrass nucleus version 2.9.0 release. | 
|  2.1.7  | Version updated for Greengrass nucleus version 2.8.0 release. | 
|  2.1.6  |  Version updated for Greengrass nucleus version 2.7.0 release.  | 
|  2.1.5  |  Version updated for Greengrass nucleus version 2.6.0 release.  | 
|  2.1.4  |  Version updated for Greengrass nucleus version 2.5.0 release.  | 
|  2.1.3  |  Version updated for Greengrass nucleus version 2.4.0 release.  | 
|  2.1.2  |  Version updated for Greengrass nucleus version 2.3.0 release.  | 
|  2.1.1  |  Version updated for Greengrass nucleus version 2.2.0 release.  | 
|  2.1.0  |  Initial version.  | 

# TensorFlow Lite runtime


The TensorFlow Lite runtime component (`variant.TensorFlowLite`) contains a script that installs [TensorFlow Lite](https://www.tensorflow.org/lite/guide/python) version 2.5.0 and its dependencies in a virtual environment on your device. The [TensorFlow Lite image classification](tensorflow-lite-image-classification-component.md) and [TensorFlow Lite object detection](tensorflow-lite-object-detection-component.md) component use this runtime component as a dependency for installing TensorFlow Lite. 

**Note**  
TensorFlow Lite runtime component v2.5.6 and later reinstalls existing installations of the TensorFlow Lite runtime and its dependencies. This reinstallation helps to ensure that the core device runs compatible versions of TensorFlow Lite and its dependencies.

To use a different runtime, you can use the recipe of this component as a template to [create a custom machine learning component](ml-customization.md).

**Topics**
+ [

## Versions
](#tensorflow-lite-component-versions)
+ [

## Type
](#tensorflow-lite-component-type)
+ [

## Operating system
](#tensorflow-lite-component-os-support)
+ [

## Requirements
](#tensorflow-lite-component-requirements)
+ [

## Dependencies
](#tensorflow-lite-component-dependencies)
+ [

## Configuration
](#tensorflow-lite-component-configuration)
+ [

## Usage
](#tensorflow-lite-component-usage)
+ [

## Local log file
](#tensorflow-lite-component-log-file)
+ [

## Changelog
](#tensorflow-lite-component-changelog)

## Versions


This component has the following versions:
+ 2.5.x

## Type


<a name="public-component-type-generic"></a>This <a name="public-component-type-generic-phrase"></a>component is a generic component (`aws.greengrass.generic`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs the component's lifecycle scripts.

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on core devices that run the following operating systems:
+ Linux
+ Windows

## Requirements


This component has the following requirements:<a name="ml-component-requirements"></a>
+ On Greengrass core devices running Amazon Linux 2 or Ubuntu 18.04, [GNU C Library](https://www.gnu.org/software/libc/) (glibc) version 2.27 or later installed on the device.
+ On Armv7l devices, such as Raspberry Pi, dependencies for OpenCV-Python installed on the device. Run the following command to install the dependencies.

  ```
  sudo apt-get install libopenjp2-7 libilmbase23 libopenexr-dev libavcodec-dev libavformat-dev libswscale-dev libv4l-dev libgtk-3-0 libwebp-dev
  ```
+ Raspberry Pi devices that run Raspberry Pi OS Bullseye must meet the following requirements:
  + NumPy 1.22.4 or later installed on the device. Raspberry Pi OS Bullseye includes an earlier version of NumPy, so you can run the following command to upgrade NumPy on the device.

    ```
    pip3 install --upgrade numpy
    ```
  + The legacy camera stack enabled on the device. Raspberry Pi OS Bullseye includes a new camera stack that is enabled by default and isn't compatible, so you must enable the legacy camera stack.<a name="raspberry-pi-bullseye-enable-legacy-camera-stack"></a>

**To enable the legacy camera stack**

    1. Run the following command to open the Raspberry Pi configuration tool.

       ```
       sudo raspi-config
       ```

    1. Select **Interface Options**.

    1. Select **Legacy camera** to enable the legacy camera stack.

    1. Reboot the Raspberry Pi.

### Endpoints and ports


By default, this component uses an installer script to install packages using the `apt`, `yum`, `brew`, and `pip` commands, depending on what platform the core device uses. This component must be able to perform outbound requests to various package indexes and repositories to run the installer script. To allow this component's outbound traffic through a proxy or firewall, you must identify the endpoints for the package indexes and repositories where your core device connects to install.

Consider the following when you identify endpoints required for this component's install script:
+ The endpoints depend on the core device's platform. For example, a core device that runs Ubuntu uses `apt` rather than `yum` or `brew`. Additionally, devices that use the same package index might have different source lists, so they might retrieve packages from different repositories.
+ The endpoints might differ between multiple devices that use the same package index, because each device has its own source lists that define where to retrieve packages.
+ The endpoints might change over time. Each package index provides the URLs of the repositories where you download packages, and the owner of a package can change what URLs the package index provides.

For more information about the dependencies that this component installs, and how to disable the installer script, see the [UseInstaller](#tensorflow-lite-component-config-useinstaller-term) configuration parameter.

For more information about endpoints and ports required for basic operation, see [Allow device traffic through a proxy or firewall](allow-device-traffic.md).

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#tensorflow-lite-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

------
#### [ 2.5.14 and 2.5.15 ]

The following table lists the dependencies for version 2.5.14 and 2.5.15 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.13.0 | Soft | 

------
#### [ 2.5.13 ]

The following table lists the dependencies for version 2.5.13 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.12.0 | Soft | 

------
#### [ 2.5.12 ]

The following table lists the dependencies for version 2.5.12 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.11.0 | Soft | 

------
#### [ 2.5.11 ]

The following table lists the dependencies for version 2.5.11 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.10.0 | Soft | 

------
#### [ 2.5.10 ]

The following table lists the dependencies for version 2.5.10 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.9.0 | Soft | 

------
#### [ 2.5.9 ]

The following table lists the dependencies for version 2.5.9 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.8.0 | Soft | 

------
#### [ 2.5.8 ]

The following table lists the dependencies for version 2.5.8 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.7.0 | Soft | 

------
#### [ 2.5.5 - 2.5.7 ]

The following table lists the dependencies for versions 2.5.5 through 2.5.7 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.6.0 | Soft | 

------
#### [ 2.5.3 and 2.5.4 ]

The following table lists the dependencies for versions 2.5.3 and 2.5.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.5.0 | Soft | 

------
#### [ 2.5.2 ]

The following table lists the dependencies for version 2.5.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.4.0 | Soft | 

------
#### [ 2.5.1 ]

The following table lists the dependencies for version 2.5.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.3.0 | Soft | 

------
#### [ 2.5.0 ]

The following table lists the dependencies for version 2.5.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.2.0 | Soft | 

------

For more information about component dependencies, see the [component recipe reference](component-recipe-reference.md#recipe-reference-component-dependencies).

## Configuration


This component provides the following configuration parameters that you can customize when you deploy the component.

`MLRootPath`  
<a name="ml-config-mlrootpath-desc"></a>(Optional) The path of the folder on Linux core devices where inference components read images and write inference results. You can modify this value to any location on your device to which the user running this component has read/write access.  
<a name="ml-config-mlrootpath-default-tfl"></a>Default: `/greengrass/v2/work/variant.TensorFlowLite/greengrass_ml`

`WindowsMLRootPath`  
This feature is available in v1.6.6 and later of this component.  
<a name="ml-config-windowsmlrootpath-desc"></a>(Optional) The path of the folder on Windows core device where inference components read images and write inference results. You can modify this value to any location on your device to which the user running this component has read/write access.  
<a name="ml-config-windowsmlrootpath-default-dlr"></a>Default: `C:\greengrass\v2\\work\\variant.DLR\\greengrass_ml`

  `UseInstaller`   
<a name="ml-config-useinstaller-desc-tfl"></a>(Optional) String value that defines whether to use the installer script in this component to install TensorFlow Lite and its dependencies. Supported values are `true` and `false`.   <a name="ml-config-useinstaller-libraries-tfl"></a>

Set this value to `false` if you want to use a custom script for TensorFlow Lite installation, or if you want to include runtime dependencies in a pre-built Linux image. To use this component with the AWS-provided TensorFlow Lite inference components, install the following libraries, including any dependencies, and make them available to the system user, such as `ggc_user`, that runs the ML components.
+ [Python](https://www.python.org/downloads/) 3.8 or later, including `pip` for your version of Python
+ [TensorFlow Lite](https://www.tensorflow.org/lite/guide/python) v2.5.0
+ [NumPy](https://numpy.org/install/)
+ [OpenCV-Python](https://pypi.org/project/opencv-python/)
+ [AWS IoT Device SDK v2 for Python](https://github.com/aws/aws-iot-device-sdk-python-v2)
+ [AWS Common Runtime (CRT) Python](https://github.com/awslabs/aws-crt-python)
+ [Picamera](https://picamera.readthedocs.io/en/release-1.13/) (for Raspberry Pi devices)
+ [`awscam` module](https://docs.aws.amazon.com/deeplens/latest/dg/deeplens-library-awscam-module.html) (for AWS DeepLens devices)
+ libGL (for Linux devices)
<a name="ml-config-useinstaller-default"></a>Default: `true`

## Usage


Use this component with the `UseInstaller` configuration parameter set to `true` to install TensorFlow Lite and its dependencies on your device. The component sets up a virtual environment on your device that includes the OpenCV and NumPy libraries that are required for TensorFlow Lite. 

**Note**  <a name="ml-installer-component-usage-note"></a>
The installer script in this component also installs the latest versions of additional system libraries that are required to configure the virtual environment on your device and to use the installed machine learning framework. This might upgrade the existing system libraries on your device. Review the following table for the list of libraries that this component installs for each supported operating system. If you want to customize this installation process, set the `UseInstaller` configuration parameter to `false`, and develop your own installer script.


| Platform | Libraries installed on the device system | Libraries installed in the virtual environment | 
| --- | --- | --- | 
| Armv7l | build-essential, cmake, ca-certificates, git | setuptools, wheel | 
| Amazon Linux 2 | mesa-libGL | None | 
| Ubuntu | wget | None | 

When you deploy your inference component, this runtime component first verifies if your device already has TensorFlow Lite and its dependencies installed. If not, then the runtime component installs them for you. 

## Local log file


This component uses the following log file.

------
#### [ Linux ]

```
/greengrass/v2/logs/variant.TensorFlowLite.log
```

------
#### [ Windows ]

```
C:\greengrass\v2\logs\variant.TensorFlowLite.log
```

------

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the path to the AWS IoT Greengrass root folder.

------
#### [ Linux ]

  ```
  sudo tail -f /greengrass/v2/logs/variant.TensorFlowLite.log
  ```

------
#### [ Windows (PowerShell) ]

  ```
  Get-Content C:\greengrass\v2\logs\variant.TensorFlowLite.log -Tail 10 -Wait
  ```

------

## Changelog


The following table describes the changes in each version of the component.


|  Version  |  Changes  | 
| --- | --- | 
|  2.5.15  |  Version updated for Greengrass nucleus 2.12.5 release.  | 
|  2.5.14  | Version updated for Greengrass nucleus version 2.12.0 release. | 
|  2.5.13  | Version updated for Greengrass nucleus version 2.11.0 release. | 
|  2.5.12  | Version updated for Greengrass nucleus version 2.10.0 release. | 
|  2.5.11  | Version updated for Greengrass nucleus version 2.9.0 release. | 
|  2.5.10  | Version updated for Greengrass nucleus version 2.8.0 release. | 
|  2.5.9  |  Version updated for Greengrass nucleus version 2.7.0 release.  | 
|  2.5.8  |  Version updated for Greengrass nucleus version 2.6.0 release.  | 
|  2.5.7  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/tensorflow-lite-component.html)  | 
|  2.5.6  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/tensorflow-lite-component.html)  | 
|  2.5.5  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/tensorflow-lite-component.html)  | 
|  2.5.4  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/tensorflow-lite-component.html)  | 
|  2.5.3  |  Version updated for Greengrass nucleus version 2.4.0 release.  | 
|  2.5.2  |  Version updated for Greengrass nucleus version 2.3.0 release.  | 
|  2.5.1  |  Version updated for Greengrass nucleus version 2.2.0 release.  | 
|  2.5.0  |  Initial version.  | 

# Modbus-RTU protocol adapter
Modbus-RTU protocol adapter v2.1.10 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/modbus-rtu-protocol-adapter-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/modbus-rtu-protocol-adapter-component.html)

Modbus-RTU protocol adapter component v2.1.10 is available.Modbus-RTU protocol adapter v2.1.9 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/modbus-rtu-protocol-adapter-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/modbus-rtu-protocol-adapter-component.html)

Modbus-RTU protocol adapter component v2.1.9 is available.Modbus-RTU protocol adapter v2.1.5 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/modbus-rtu-protocol-adapter-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/modbus-rtu-protocol-adapter-component.html)

Modbus-RTU protocol adapter component v2.1.5 is available. This release fixes an issue with the `ReadDiscreteInput` operation.Modbus-RTU protocol adapter v2.1.0 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/modbus-rtu-protocol-adapter-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/modbus-rtu-protocol-adapter-component.html)

Modbus-RTU protocol adapter component v2.1.0 is available. This release adds new parameters that you can specify to configure serial communication with Modbus RTU devices.

The Modbus-RTU protocol adapter component (`aws.greengrass.Modbus`) polls information from local Modbus RTU devices.

To request information from a local Modbus RTU device with this component, publish a message to the topic where this component subscribes. In the message, specify the Modbus RTU request to send to a device. Then, this component publishes a response that contains the result of the Modbus RTU request.

**Note**  
This component provides similar functionality to the Modbus RTU protocol adapter connector in AWS IoT Greengrass V1. For more information, see [Modbus RTU protocol adapter connector](https://docs.aws.amazon.com/greengrass/latest/developerguide/modbus-protocol-adapter-connector.html) in the *AWS IoT Greengrass V1 Developer Guide*.

**Topics**
+ [

## Versions
](#modbus-rtu-protocol-adapter-component-versions)
+ [

## Type
](#modbus-rtu-protocol-adapter-component-type)
+ [

## Operating system
](#modbus-rtu-protocol-adapter-component-os-support)
+ [

## Requirements
](#modbus-rtu-protocol-adapter-component-requirements)
+ [

## Dependencies
](#modbus-rtu-protocol-adapter-component-dependencies)
+ [

## Configuration
](#modbus-rtu-protocol-adapter-component-configuration)
+ [

## Input data
](#modbus-rtu-protocol-adapter-component-input-data)
+ [

## Output data
](#modbus-rtu-protocol-adapter-component-output-data)
+ [

## Modbus RTU requests and responses
](#modbus-rtu-protocol-adapter-component-requests-responses)
+ [

## Local log file
](#modbus-rtu-protocol-adapter-component-log-file)
+ [

## Licenses
](#modbus-rtu-protocol-adapter-component-licenses)
+ [

## Changelog
](#modbus-rtu-protocol-adapter-component-changelog)

## Versions


This component has the following versions:
+ 2.1.x
+ 2.0.x

## Type


<a name="public-component-type-lambda"></a>This <a name="public-component-type-lambda-phrase"></a>component is a Lambda component (`aws.greengrass.lambda`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs this component's Lambda function using the [Lambda launcher component](lambda-launcher-component.md).

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on Linux core devices only.

## Requirements


This component has the following requirements:
+ <a name="core-device-lambda-function-requirements"></a>Your core device must meet the requirements to run Lambda functions. If you want the core device to run containerized Lambda functions, the device must meet the requirements to do so. For more information, see [Lambda function requirements](setting-up.md#greengrass-v2-lambda-requirements).
+ <a name="public-component-python3-requirement"></a>[Python](https://www.python.org/) version 3.7 installed on the core device and added to the PATH environment variable.
+ A physical connection between the AWS IoT Greengrass core device and the Modbus devices. The core device must be physically connected to the Modbus RTU network through a serial port, such as a USB port.
+ <a name="connector-component-legacy-subscription-router-dependency"></a>To receive output data from this component, you must merge the following configuration update for the [legacy subscription router component](legacy-subscription-router-component.md) (`aws.greengrass.LegacySubscriptionRouter`) when you deploy this component. This configuration specifies the topic where this component publishes responses.

------
#### [ Legacy subscription router v2.1.x ]

  ```
  {
    "subscriptions": {
      "aws-greengrass-modbus": {
        "id": "aws-greengrass-modbus",
        "source": "component:aws.greengrass.Modbus",
        "subject": "modbus/adapter/response",
        "target": "cloud"
      }
    }
  }
  ```

------
#### [ Legacy subscription router v2.0.x ]

  ```
  {
    "subscriptions": {
      "aws-greengrass-modbus": {
        "id": "aws-greengrass-modbus",
        "source": "arn:aws:lambda:region:aws:function:aws-greengrass-modbus:version",
        "subject": "modbus/adapter/response",
        "target": "cloud"
      }
    }
  }
  ```<a name="connector-component-legacy-subscription-router-dependency-replace"></a>
  + Replace *region* with the AWS Region that you use.
  + Replace *version* with the version of the Lambda function that this component runs. To find the Lambda function version, you must view the recipe for the version of this component that you want to deploy. Open this component's details page in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass), and look for the **Lambda function** key-value pair. This key-value pair contains the name and version of the Lambda function.

**Important**  <a name="connector-component-legacy-subscription-router-dependency-note"></a>
You must update the Lambda function version on the legacy subscription router every time you deploy this component. This ensures that you use the correct Lambda function version for the component version that you deploy.

------

  <a name="connector-component-create-deployments"></a>For more information, see [Create deployments](create-deployments.md).
+ The Modbus-RTU protocol adapter is supported to run in a VPC.

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#modbus-rtu-protocol-adapter-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

------
#### [ 2.1.11 ]

The following table lists the dependencies for version 2.1.11 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.16.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.1.10 ]

The following table lists the dependencies for version 2.1.10 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.15.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.1.9 ]

The following table lists the dependencies for version 2.1.9 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.14.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.1.8 ]

The following table lists the dependencies for version 2.1.8 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.13.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.1.7 ]

The following table lists the dependencies for version 2.1.7 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.12.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.1.6 ]

The following table lists the dependencies for version 2.1.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.11.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.1.4 and 2.1.5 ]

The following table lists the dependencies for versions 2.1.4 and 2.1.5 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.10.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.1.3 ]

The following table lists the dependencies for version 2.1.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.9.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.1.2 ]

The following table lists the dependencies for version 2.1.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.8.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.1.1 ]

The following table lists the dependencies for version 2.1.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.7.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.0.8 and 2.1.0 ]

The following table lists the dependencies for versions 2.0.8 and 2.1.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.6.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.0.7 ]

The following table lists the dependencies for version 2.0.7 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.5.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.0.6 ]

The following table lists the dependencies for version 2.0.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.4.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.0.5 ]

The following table lists the dependencies for version 2.0.5 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.3.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.0.4 ]

The following table lists the dependencies for version 2.0.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.2.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.0.3 ]

The following table lists the dependencies for version 2.0.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.3 <2.1.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | >=1.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | >=1.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | >=1.0.0  | Hard | 

------

For more information about component dependencies, see the [component recipe reference](component-recipe-reference.md#recipe-reference-component-dependencies).

## Configuration


This component provides the following configuration parameters that you can customize when you deploy the component.

**Note**  <a name="connector-component-lambda-parameters"></a>
This component's default configuration includes Lambda function parameters. We recommend that you edit only the following parameters to configure this component on your devices.

------
#### [ v2.1.x ]

`lambdaParams`  
An object that contains the parameters for this component's Lambda function. This object contains the following information:    
`EnvironmentVariables`  
An object that contains the Lambda function's parameters. This object contains the following information:    
`ModbusLocalPort`  <a name="modbus-rtu-protocol-adapter-configuration-modbuslocalport"></a>
The absolute path to the physical Modbus serial port on the core device, such as `/dev/ttyS2`.  
To run this component in a container, you must define this path as a system device (in `containerParams.devices`) that the component can access. This component runs in a container by default.  
This component must have read/write access to the device.  
`ModbusBaudRate`  
(Optional) A string value that specifies the baud rate for serial communication with local Modbus TCP devices.  
Default: `9600`  
`ModbusByteSize`  
(Optional) A string value that specifies the size of a byte in serial communication with local Modbus TCP devices. Choose `5`, `6`, `7`, or `8` bits.  
Default: `8`  
`ModbusParity`  
(Optional) The parity mode to use to verify data integrity in serial communication with local Modbus TCP devices.  
+ `E` – Verify data integrity with even parity.
+ `O` – Verify data integrity with odd parity.
+ `N` – Don't verify data integrity.
Default: `N`  
`ModbusStopBits`  
(Optional) A string value that specifies the number of bits that indicate the end of a byte in serial communication with local Modbus TCP devices.  
Default: `1`

`containerMode`  <a name="modbus-rtu-protocol-adapter-configuration-containermode"></a>
(Optional) The containerization mode for this component. Choose from the following options:  
+ `GreengrassContainer` – The component runs in an isolated runtime environment inside the AWS IoT Greengrass container.

  If you specify this option, you must specify a system device (in `containerParams.devices`) to give the container access to the Modbus device.
+ `NoContainer` – The component doesn't run in an isolated runtime environment.
Default: `GreengrassContainer`

`containerParams`  <a name="modbus-rtu-protocol-adapter-configuration-containerparams"></a>
<a name="connector-component-container-params-description"></a>(Optional) An object that contains the container parameters for this component. The component uses these parameters if you specify `GreengrassContainer` for `containerMode`.  
This object contains the following information:    
`memorySize`  
<a name="connector-component-container-params-memory-size-description"></a>(Optional) The amount of memory (in kilobytes) to allocate to the component.  
Defaults to 512 MB (525,312 KB).  
`devices`  
(Optional) An object that specifies the system devices that the component can access in a container.  
To run this component in a container, you must specify the system device that you configure in the `ModbusLocalPort` environment variable.
This object contains the following information:    
`0` – This is an array index as a string.  
An object that contains the following information:    
`path`  
The path to the system device on the core device. This must have the same value as the value that you configure for `ModbusLocalPort`.  
`permission`  
(Optional) The permission to access the system device from the container. This value must be `rw`, which specifies that the component has read/write access to the system device.  
Default: `rw`  
`addGroupOwner`  
(Optional) Whether or not to add the system group that runs the component as an owner of the system device.  
Default: `true`

`pubsubTopics`  <a name="connector-component-pubsub-topics-parameter"></a>
(Optional) An object that contains the topics where the component subscribes to receive messages. You can specify each topic and whether the component subscribes to MQTT topics from AWS IoT Core or local publish/subscribe topics.  
This object contains the following information:    
`0` – This is an array index as a string.  
An object that contains the following information:    
`type`  
(Optional) The type of publish/subscribe messaging that this component uses to subscribe to messages. Choose from the following options:  
+ `PUB_SUB` – Subscribe to local publish/subscribe messages. If you choose this option, the topic can't contain MQTT wildcards. For more information about how to send messages from custom component when you specify this option, see [Publish/subscribe local messages](ipc-publish-subscribe.md).
+ `IOT_CORE` – Subscribe to AWS IoT Core MQTT messages. If you choose this option, the topic can contain MQTT wildcards. For more information about how to send messages from custom components when you specify this option, see [Publish/subscribe AWS IoT Core MQTT messages](ipc-iot-core-mqtt.md).
Default: `PUB_SUB`  
`topic`  
(Optional) The topic to which the component subscribes to receive messages. If you specify `IotCore` for `type`, you can use MQTT wildcards (`+` and `#`) in this topic.

**Example: Configuration merge update (container mode)**  <a name="modbus-rtu-protocol-adapter-configuration-example-container-mode"></a>

```
{
  "lambdaExecutionParameters": {
    "EnvironmentVariables": {
      "ModbusLocalPort": "/dev/ttyS2"
    }
  },
  "containerMode": "GreengrassContainer",
  "containerParams": {
    "devices": {
      "0": {
        "path": "/dev/ttyS2",
        "permission": "rw",
        "addGroupOwner": true
      }
    }
  }
}
```

**Example: Configuration merge update (no container mode)**  <a name="modbus-rtu-protocol-adapter-configuration-example-no-container-mode"></a>

```
{
  "lambdaExecutionParameters": {
    "EnvironmentVariables": {
      "ModbusLocalPort": "/dev/ttyS2"
    }
  },
  "containerMode": "NoContainer"
}
```

------
#### [ v2.0.x ]

`lambdaParams`  
An object that contains the parameters for this component's Lambda function. This object contains the following information:    
`EnvironmentVariables`  
An object that contains the Lambda function's parameters. This object contains the following information:    
`ModbusLocalPort`  <a name="modbus-rtu-protocol-adapter-configuration-modbuslocalport"></a>
The absolute path to the physical Modbus serial port on the core device, such as `/dev/ttyS2`.  
To run this component in a container, you must define this path as a system device (in `containerParams.devices`) that the component can access. This component runs in a container by default.  
This component must have read/write access to the device.

`containerMode`  <a name="modbus-rtu-protocol-adapter-configuration-containermode"></a>
(Optional) The containerization mode for this component. Choose from the following options:  
+ `GreengrassContainer` – The component runs in an isolated runtime environment inside the AWS IoT Greengrass container.

  If you specify this option, you must specify a system device (in `containerParams.devices`) to give the container access to the Modbus device.
+ `NoContainer` – The component doesn't run in an isolated runtime environment.
Default: `GreengrassContainer`

`containerParams`  <a name="modbus-rtu-protocol-adapter-configuration-containerparams"></a>
<a name="connector-component-container-params-description"></a>(Optional) An object that contains the container parameters for this component. The component uses these parameters if you specify `GreengrassContainer` for `containerMode`.  
This object contains the following information:    
`memorySize`  
<a name="connector-component-container-params-memory-size-description"></a>(Optional) The amount of memory (in kilobytes) to allocate to the component.  
Defaults to 512 MB (525,312 KB).  
`devices`  
(Optional) An object that specifies the system devices that the component can access in a container.  
To run this component in a container, you must specify the system device that you configure in the `ModbusLocalPort` environment variable.
This object contains the following information:    
`0` – This is an array index as a string.  
An object that contains the following information:    
`path`  
The path to the system device on the core device. This must have the same value as the value that you configure for `ModbusLocalPort`.  
`permission`  
(Optional) The permission to access the system device from the container. This value must be `rw`, which specifies that the component has read/write access to the system device.  
Default: `rw`  
`addGroupOwner`  
(Optional) Whether or not to add the system group that runs the component as an owner of the system device.  
Default: `true`

`pubsubTopics`  <a name="connector-component-pubsub-topics-parameter"></a>
(Optional) An object that contains the topics where the component subscribes to receive messages. You can specify each topic and whether the component subscribes to MQTT topics from AWS IoT Core or local publish/subscribe topics.  
This object contains the following information:    
`0` – This is an array index as a string.  
An object that contains the following information:    
`type`  
(Optional) The type of publish/subscribe messaging that this component uses to subscribe to messages. Choose from the following options:  
+ `PUB_SUB` – Subscribe to local publish/subscribe messages. If you choose this option, the topic can't contain MQTT wildcards. For more information about how to send messages from custom component when you specify this option, see [Publish/subscribe local messages](ipc-publish-subscribe.md).
+ `IOT_CORE` – Subscribe to AWS IoT Core MQTT messages. If you choose this option, the topic can contain MQTT wildcards. For more information about how to send messages from custom components when you specify this option, see [Publish/subscribe AWS IoT Core MQTT messages](ipc-iot-core-mqtt.md).
Default: `PUB_SUB`  
`topic`  
(Optional) The topic to which the component subscribes to receive messages. If you specify `IotCore` for `type`, you can use MQTT wildcards (`+` and `#`) in this topic.

**Example: Configuration merge update (container mode)**  <a name="modbus-rtu-protocol-adapter-configuration-example-container-mode"></a>

```
{
  "lambdaExecutionParameters": {
    "EnvironmentVariables": {
      "ModbusLocalPort": "/dev/ttyS2"
    }
  },
  "containerMode": "GreengrassContainer",
  "containerParams": {
    "devices": {
      "0": {
        "path": "/dev/ttyS2",
        "permission": "rw",
        "addGroupOwner": true
      }
    }
  }
}
```

**Example: Configuration merge update (no container mode)**  <a name="modbus-rtu-protocol-adapter-configuration-example-no-container-mode"></a>

```
{
  "lambdaExecutionParameters": {
    "EnvironmentVariables": {
      "ModbusLocalPort": "/dev/ttyS2"
    }
  },
  "containerMode": "NoContainer"
}
```

------

## Input data


This component accepts Modbus RTU request parameters on the following topic and sends the Modbus RTU request to the device. <a name="connector-component-local-publish"></a>By default, this component subscribes to local publish/subscribe messages. For more information about how to publish messages to this component from your custom components, see [Publish/subscribe local messages](ipc-publish-subscribe.md). 

**Default topic (local publish/subscribe):** `modbus/adapter/request`

<a name="connector-component-input-properties"></a>The message accepts the following properties. Input messages must be in JSON format.

`request`  
The parameters for the Modbus RTU request to send.  
The shape of the request message depends on the type of Modbus RTU request that it represents. The following properties are required for all requests.  
Type: `object` that contains the following information:    
`operation`  
The name of the operation to run. For example, specify `ReadCoilsRequest` to read coils on a Modbus RTU device. For more information about supported operations, see [Modbus RTU requests and responses](#modbus-rtu-protocol-adapter-component-requests-responses).  
Type: `string`  
`device`  
The target device of the request.  
This value must be an integer between `0` and `247`.  
Type: `integer`
The other parameters to include in the request depend on the operation. This component handles the [cyclic redundancy check (CRC)](https://en.wikipedia.org/wiki/Cyclic_redundancy_check) to verify data requests for you.  
If you request includes an `address` property, you must specify its value as an integer. For example, `"address": 1`.

`id`  <a name="connector-component-input-property-id"></a>
An arbitrary ID for the request. Use this property to map an input request to an output response. When you specify this property, the component sets the `id` property in the response object to this value.  
Type: `string`

**Example input: Read coils request**  

```
{
  "request": {
    "operation": "ReadCoilsRequest",
    "device": 1,
    "address": 1,
    "count": 1
  },
  "id": "MyRequest"
}
```

## Output data


 <a name="connector-component-output-data"></a>This component publishes responses as output data on the following MQTT topic by default. You must specify this topic as the `subject` in the configuration for the [legacy subscription router component](legacy-subscription-router-component.md). For more information about how to subscribe to messages on this topic in your custom components, see [Publish/subscribe AWS IoT Core MQTT messages](ipc-iot-core-mqtt.md). 

**Default topic (AWS IoT Core MQTT):** `modbus/adapter/response`

The shape of the response message depends on the request operation and the response status. For examples, see [Example requests and responses](#modbus-rtu-protocol-adapter-component-examples).

Every response includes the following properties:

`response`  
The response from the Modbus RTU device.  
Type: `object` that contains the following information:    
`status`  
The status of the request. The status can be one of the following values:  
+ `Success` – The request was valid, the component sent the request to the Modbus RTU network, and the Modbus RTU network returned a response.
+ `Exception` – The request was valid, the component sent the request to the Modbus RTU network, and the Modbus RTU network returned an exception. For more information, see [Response status: Exception](#modbus-rtu-protocol-adapter-component-response-exception).
+ `No Response` – The request was invalid, and the component caught the error before it sent the request to the Modbus RTU network. For more information, see [Response status: No response](#modbus-rtu-protocol-adapter-component-response-noresponse).  
`operation`  
The operation that the component requested.  
`device`  
The device where the component sent the request.  
`payload`  
The response from the Modbus RTU device. If the `status` is `No Response`, this object contains only an `error` property with the description of the error (for example, `[Input/Output] No Response received from the remote unit`).

`id`  
The ID of the request, which you can use to identify which response corresponds to which request.

**Note**  
A response for a write operation is simply an echo of the request. Although write responses don't include meaningful information, it's a good practice to check the status of the response to see if the request succeeds or fails.

**Example output: Success**  

```
{
  "response" : {
    "status" : "success",
    "device": 1,
    "operation": "ReadCoilsRequest",
    "payload": {
      "function_code": 1,
      "bits": [1]
    }
  },
  "id" : "MyRequest"
}
```

**Example output: Failure**  

```
{
  "response" : {
    "status" : "fail",
    "error_message": "Internal Error",
    "error": "Exception",
    "device": 1,
    "operation": "ReadCoilsRequest",
    "payload": {
      "function_code": 129,
      "exception_code": 2
    }
  },
  "id" : "MyRequest"
}
```

For more examples, see [Example requests and responses](#modbus-rtu-protocol-adapter-component-examples).

## Modbus RTU requests and responses


This connector accepts Modbus RTU request parameters as [input data](#modbus-rtu-protocol-adapter-component-input-data) and publishes responses as [output data](#modbus-rtu-protocol-adapter-component-output-data).

The following common operations are supported.


| Operation name in request | Function code in response | 
| --- | --- | 
| ReadCoilsRequest | 01 | 
| ReadDiscreteInputsRequest | 02 | 
| ReadHoldingRegistersRequest | 03 | 
| ReadInputRegistersRequest | 04 | 
| WriteSingleCoilRequest | 05 | 
| WriteSingleRegisterRequest | 06 | 
| WriteMultipleCoilsRequest | 15 | 
| WriteMultipleRegistersRequest | 16 | 
| MaskWriteRegisterRequest | 22 | 
| ReadWriteMultipleRegistersRequest | 23 | 

### Example requests and responses


The following are example requests and responses for supported operations.

Read coils  
**Request example:**  

```
{
  "request": {
    "operation": "ReadCoilsRequest",
    "device": 1,
    "address": 1,
    "count": 1
  },
  "id": "TestRequest"
}
```
**Response example:**  

```
{
  "response": {
    "status": "success",
    "device": 1,
    "operation": "ReadCoilsRequest",
    "payload": {
      "function_code": 1,
      "bits": [1]
    }
  },
  "id" : "TestRequest"
}
```

Read discrete inputs  
**Request example:**  

```
{
  "request": {
    "operation": "ReadDiscreteInputsRequest",
    "device": 1,
    "address": 1,
    "count": 1
  },
  "id": "TestRequest"
}
```
**Response example:**  

```
{
  "response": {
    "status": "success",
    "device": 1,
    "operation": "ReadDiscreteInputsRequest",
    "payload": {
      "function_code": 2,
      "bits": [1]
    }
  },
  "id" : "TestRequest"
}
```

Read holding registers  
**Request example:**  

```
{
  "request": {
    "operation": "ReadHoldingRegistersRequest",
    "device": 1,
    "address": 1,
    "count": 1
  },
  "id": "TestRequest"
}
```
**Response example:**  

```
{
  "response": {
    "status": "success",
    "device": 1,
    "operation": "ReadHoldingRegistersRequest",
    "payload": {
      "function_code": 3,
      "registers": [20,30]
    }
  },
  "id" : "TestRequest"
}
```

Read input registers  
**Request example:**  

```
{
  "request": {
    "operation": "ReadInputRegistersRequest",
    "device": 1,
    "address": 1,
    "count": 1
  },
  "id": "TestRequest"
}
```

Write single coil  
**Request example:**  

```
{
  "request": {
    "operation": "WriteSingleCoilRequest",
    "device": 1,
    "address": 1,
    "value": 1
  },
  "id": "TestRequest"
}
```
**Response example:**  

```
{
  "response": {
    "status": "success",
    "device": 1,
    "operation": "WriteSingleCoilRequest",
    "payload": {
      "function_code": 5,
      "address": 1,
      "value": true
    }
  },
  "id" : "TestRequest"
}
```

Write single register  
**Request example:**  

```
{
  "request": {
    "operation": "WriteSingleRegisterRequest",
    "device": 1,
    "address": 1,
    "value": 1
  },
  "id": "TestRequest"
}
```

Write multiple coils  
**Request example:**  

```
{
  "request": {
    "operation": "WriteMultipleCoilsRequest",
    "device": 1,
    "address": 1,
    "values": [1,0,0,1]
  },
  "id": "TestRequest"
}
```
**Response example:**  

```
{
  "response": {
    "status": "success",
    "device": 1,
    "operation": "WriteMultipleCoilsRequest",
    "payload": {
      "function_code": 15,
      "address": 1,
      "count": 4
    }
  },
  "id" : "TestRequest"
}
```

Write multiple registers  
**Request example:**  

```
{
  "request": {
    "operation": "WriteMultipleRegistersRequest",
    "device": 1,
    "address": 1,
    "values": [20,30,10]
  },
  "id": "TestRequest"
}
```
**Response example:**  

```
{
  "response": {
    "status": "success",
    "device": 1,
    "operation": "WriteMultipleRegistersRequest",
    "payload": {
      "function_code": 23,
      "address": 1,
      "count": 3
    }
  },
  "id" : "TestRequest"
}
```

Mask write register  
**Request example:**  

```
{
  "request": {
    "operation": "MaskWriteRegisterRequest",
    "device": 1,
    "address": 1,
    "and_mask": 175,
    "or_mask": 1
  },
  "id": "TestRequest"
}
```
**Response example:**  

```
{
  "response": {
    "status": "success",
    "device": 1,
    "operation": "MaskWriteRegisterRequest",
    "payload": {
      "function_code": 22,
      "and_mask": 0,
      "or_mask": 8
    }
  },
  "id" : "TestRequest"
}
```

Read write multiple registers  
**Request example:**  

```
{
  "request": {
    "operation": "ReadWriteMultipleRegistersRequest",
    "device": 1,
    "read_address": 1,
    "read_count": 2,
    "write_address": 3,
    "write_registers": [20,30,40]
  },
  "id": "TestRequest"
}
```
**Response example:**  

```
{
  "response": {
    "status": "success",
    "device": 1,
    "operation": "ReadWriteMultipleRegistersRequest",
    "payload": {
      "function_code": 23,
      "registers": [10,20,10,20]
    }
  },
  "id" : "TestRequest"
}
```
The response includes the registers that the component reads.

### Response status: Exception


Exceptions can occur when the request format is valid, but the request is not completed successfully. In this case, the response contains the following information:
+ The `status` is set to `Exception`.
+ The `function_code` equals the function code of the request \$1 128.
+ The `exception_code` contains the exception code. For more information, see Modbus exception codes.

**Example:**

```
{
  "response": {
    "status": "fail",
    "error_message": "Internal Error",
    "error": "Exception",
    "device": 1,
    "operation": "ReadCoilsRequest",
    "payload": {
      "function_code": 129,
      "exception_code": 2
    }
  },
  "id": "TestRequest"
}
```

### Response status: No response


This connector performs validation checks on the Modbus request. For example, it checks for invalid formats and missing fields. If the validation fails, the connector doesn't send the request. Instead, it returns a response that contains the following information:
+ The `status` is set to `No Response`.
+ The `error` contains the error reason.
+ The `error_message` contains the error message.

**Examples:**

```
{
  "response": {
    "status": "fail",
    "error_message": "Invalid address field. Expected <type 'int'>, got <type 'str'>",
    "error": "No Response",
    "device": 1,
    "operation": "ReadCoilsRequest",
    "payload": {
      "error": "Invalid address field. Expected Expected <type 'int'>, got <type 'str'>"
    }
  },
  "id": "TestRequest"
}
```

If the request targets a nonexistent device or if the Modbus RTU network is not working, you might get a `ModbusIOException`, which uses the No Response format.

```
{
  "response": {
    "status": "fail",
    "error_message": "[Input/Output] No Response received from the remote unit",
    "error": "No Response",
    "device": 1,
    "operation": "ReadCoilsRequest",
    "payload": {
      "error": "[Input/Output] No Response received from the remote unit"
    }
  },
  "id": "TestRequest"
}
```

## Local log file


This component uses the following log file.

```
/greengrass/v2/logs/aws.greengrass.Modbus.log
```

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` with the path to the AWS IoT Greengrass root folder.

  ```
  sudo tail -f /greengrass/v2/logs/aws.greengrass.Modbus.log
  ```

## Licenses


This component includes the following third-party software/licensing:
+ [pymodbus](https://github.com/riptideio/pymodbus/blob/master/README.rst)/BSD License
+ [pyserial](https://github.com/pyserial/pyserial)/BSD License

<a name="component-core-software-license"></a>This component is released under the [Greengrass Core Software License Agreement](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf).

## Changelog


The following table describes the changes in each version of the component.


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.1.11  | Version updated for Greengrass nucleus version 2.15.0 release. | 
|  2.1.10  | Version updated for Greengrass nucleus version 2.14.0 release. | 
|  2.1.9  | Version updated for Greengrass nucleus version 2.13.0 release. | 
|  2.1.8  | Version updated for Greengrass nucleus version 2.12.0 release. | 
|  2.1.7  | Version updated for Greengrass nucleus version 2.11.0 release. | 
|  2.1.6  | Version updated for Greengrass nucleus version 2.10.0 release. | 
|  2.1.5  | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/modbus-rtu-protocol-adapter-component.html) | 
|  2.1.4  | Version updated for Greengrass nucleus version 2.9.0 release. | 
|  2.1.3  | Version updated for Greengrass nucleus version 2.8.0 release. | 
|  2.1.2  |  Version updated for Greengrass nucleus version 2.7.0 release.  | 
|  2.1.1  |  Version updated for Greengrass nucleus version 2.6.0 release.  | 
|  2.1.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/modbus-rtu-protocol-adapter-component.html)  | 
|  2.0.8  |  Version updated for Greengrass nucleus version 2.5.0 release.  | 
|  2.0.7  |  Version updated for Greengrass nucleus version 2.4.0 release.  | 
|  2.0.6  |  Version updated for Greengrass nucleus version 2.3.0 release.  | 
|  2.0.5  |  Version updated for Greengrass nucleus version 2.2.0 release.  | 
|  2.0.4  |  Version updated for Greengrass nucleus version 2.1.0 release.  | 
|  2.0.3  |  Initial version.  | 

# MQTT bridge
MQTT bridge v2.3.1 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/mqtt-bridge-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/mqtt-bridge-component.html)

MQTT bridge v2.3.1 is available. This release fixes a rare issue where the local MQTT client gets into a disconnect loop.MQTT bridge v2.3.0 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/mqtt-bridge-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/mqtt-bridge-component.html)

MQTT bridge v2.3.0 is available. This release adds MQTT 5 support for bridging between AWS IoT Core and local MQTT sources.

The MQTT bridge component (`aws.greengrass.clientdevices.mqtt.Bridge`) relays MQTT messages between client devices, local Greengrass publish/subscribe, and AWS IoT Core. You can use this component to act on MQTT messages from client devices in custom components and sync client devices with the AWS Cloud.

**Note**  <a name="client-device-component-context"></a>
Client devices are local IoT devices that connect to a Greengrass core device to send MQTT messages and data to process. For more information, see [Interact with local IoT devices](interact-with-local-iot-devices.md).

You can use this component to relay messages between the following message brokers:
+ Local MQTT – The local MQTT broker handles messages between client devices and a core device.
+ Local publish/subscribe – The local Greengrass message broker handles messages between components on a core device. For more information about how to interact with these messages in Greengrass components, see [Publish/subscribe local messages](ipc-publish-subscribe.md).
+ AWS IoT Core – The AWS IoT Core MQTT broker handles messages between IoT devices and AWS Cloud destinations. For more information about how to interact with these messages in Greengrass components, see [Publish/subscribe AWS IoT Core MQTT messages](ipc-iot-core-mqtt.md).
**Note**  <a name="mqtt-bridge-component-iotcore-qos-1-note"></a>
The MQTT bridge uses QoS 1 to publish and subscribe to AWS IoT Core, even when a client device uses QoS 0 to publish and subscribe to the local MQTT broker. As a result, you might observe additional latency when you relay MQTT messages from client devices on the local MQTT broker to AWS IoT Core. For more information about MQTT configuration on core devices, see [Configure MQTT timeouts and cache settings](configure-greengrass-core-v2.md#configure-mqtt).

**Topics**
+ [

## Versions
](#mqtt-bridge-component-versions)
+ [

## Type
](#mqtt-bridge-component-type)
+ [

## Operating system
](#mqtt-bridge-component-os-support)
+ [

## Requirements
](#mqtt-bridge-component-requirements)
+ [

## Dependencies
](#mqtt-bridge-component-dependencies)
+ [

## Configuration
](#mqtt-bridge-component-configuration)
+ [

## Local log file
](#mqtt-bridge-component-log-file)
+ [

## Changelog
](#mqtt-bridge-component-changelog)

## Versions


This component has the following versions:
+ 2.3.x
+ 2.2.x
+ 2.1.x
+ 2.0.x

## Type


<a name="public-component-type-plugin-para1"></a>This component is a plugin component (`aws.greengrass.plugin`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs this component in the same Java Virtual Machine (JVM) as the nucleus. The nucleus restarts when you change this component's version on the core device.

<a name="public-component-type-plugin-para2"></a>This component uses the same log file as the Greengrass nucleus. For more information, see [Monitor AWS IoT Greengrass logs](monitor-logs.md).

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on core devices that run the following operating systems:
+ Linux
+ Windows

## Requirements


This component has the following requirements:
+ If you configure the core device's MQTT broker component to use a port other than the default port 8883, you must use MQTT bridge v2.1.0 or later. Configure it to connect on the port where the broker operates.
+ The MQTT bridge component is supported to run in a VPC.

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#mqtt-bridge-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

------
#### [ 2.3.2 ]

The following table lists the dependencies for version 2.3.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Client device auth](client-device-auth-component.md) | >=2.2.0 <2.6.0 | Hard | 

------
#### [ 2.3.0 and 2.3.1 ]

The following table lists the dependencies for version 2.3.0 and 2.3.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Client device auth](client-device-auth-component.md) | >=2.2.0 <2.5.0 | Hard | 

------
#### [ 2.2.5 and 2.2.6 ]

The following table lists the dependencies for version 2.2.5 and 2.2.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Client device auth](client-device-auth-component.md) | >=2.2.0 <2.5.0 | Hard | 

------
#### [ 2.2.3 and 2.2.4 ]

The following table lists the dependencies for versions 2.2.3 and 2.2.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Client device auth](client-device-auth-component.md) | >=2.2.0 <2.4.0 | Hard | 

------
#### [ 2.2.0 – 2.2.2 ]

The following table lists the dependencies for versions 2.2.0 to 2.2.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Client device auth](client-device-auth-component.md) | >=2.2.0 <2.3.0 | Hard | 

------
#### [ 2.1.1 ]

The following table lists the dependencies for version 2.1.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Client device auth](client-device-auth-component.md) | >=2.0.0 <2.2.0 | Hard | 

------
#### [ 2.0.0 to 2.1.0 ]

The following table lists the dependencies for versions 2.0.0 through 2.1.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Client device auth](client-device-auth-component.md) | >=2.0.0 <2.1.0 | Hard | 

------

For more information about component dependencies, see the [component recipe reference](component-recipe-reference.md#recipe-reference-component-dependencies).

## Configuration


This component provides the following configuration parameters that you can customize when you deploy the component.

------
#### [ 2.3.0 – 2.3.2 ]

`mqttTopicMapping`  
<a name="mqtt-bridge-component-configuration-mqtt-topic-mapping-description"></a>The topic mappings that you want to bridge. This component subscribes to messages on the source topic and publishes the messages that it receives to the destination topic. Each topic mapping defines the topic, source type, and destination type.  
This object contains the following information:    
`topicMappingNameKey`  
<a name="mqtt-bridge-component-configuration-mqtt-topic-mapping-name-key-description"></a>The name of this topic mapping. Replace *topicMappingNameKey* with a name that helps you identify this topic mapping.  
This object contains the following information:    
`topic`  
The topic or topic filter to bridge between the source and target brokers.  
You can use the `+` and `#` MQTT topic wildcards to relay messages on all topics that match a topic filter. For more information, see [MQTT topics](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html) in the *AWS IoT Core Developer Guide*.  
To use MQTT topic wildcards with the `Pubsub` source broker, you must use v2.6.0 or later of the [Greengrass nucleus component](greengrass-nucleus-component.md).  
`targetTopicPrefix`  
The prefix to add to the target topic when this component relays the message.  
`source`  <a name="mqtt-bridge-component-configuration-mqtt-topic-mapping-source"></a>
The source message broker. Choose from the following options:  <a name="mqtt-bridge-component-configuration-topic-types"></a>
+ `LocalMqtt` – The local MQTT broker where client devices communicate.
+ `Pubsub` – The local Greengrass publish/subscribe message broker.
+ `IotCore` – The AWS IoT Core MQTT message broker.
**Note**  <a name="mqtt-bridge-component-iotcore-qos-1-note"></a>
The MQTT bridge uses QoS 1 to publish and subscribe to AWS IoT Core, even when a client device uses QoS 0 to publish and subscribe to the local MQTT broker. As a result, you might observe additional latency when you relay MQTT messages from client devices on the local MQTT broker to AWS IoT Core. For more information about MQTT configuration on core devices, see [Configure MQTT timeouts and cache settings](configure-greengrass-core-v2.md#configure-mqtt).
`source` and `target` must be different.  
`target`  <a name="mqtt-bridge-component-configuration-mqtt-topic-mapping-target"></a>
The target message broker. Choose from the following options:  <a name="mqtt-bridge-component-configuration-topic-types"></a>
+ `LocalMqtt` – The local MQTT broker where client devices communicate.
+ `Pubsub` – The local Greengrass publish/subscribe message broker.
+ `IotCore` – The AWS IoT Core MQTT message broker.
**Note**  <a name="mqtt-bridge-component-iotcore-qos-1-note"></a>
The MQTT bridge uses QoS 1 to publish and subscribe to AWS IoT Core, even when a client device uses QoS 0 to publish and subscribe to the local MQTT broker. As a result, you might observe additional latency when you relay MQTT messages from client devices on the local MQTT broker to AWS IoT Core. For more information about MQTT configuration on core devices, see [Configure MQTT timeouts and cache settings](configure-greengrass-core-v2.md#configure-mqtt).
`source` and `target` must be different.

mqtt5RouteOptions  
(Optional) Provides options for configuring topic mappings for bridging messages from the source topic to the destination topic.  
This object contains the following information:    
*mqtt5RouteOptionsNameKey*  
The name of the route options for a topic mapping. Replace *mqtt5RouteOptionsNameKey* with the matching *topicMappingNameKey* defined in the `mqttTopicMapping` field.  
This object contains the following information:    
noLocal  
(Optional) When enabled, the bridge doesn't forward messages on a topic that the bridge itself published. Use this to prevent loops, as follows:  

```
{
    "mqtt5RouteOptions": {
        "toIoTCore": {
            "noLocal": true
        }
    },
    "mqttTopicMapping": {
        "toIoTCore": {
            "topic": "device",
            "source": "LocalMqtt",
            "target": "IotCore"
        },
        "toLocal": {
            "topic": "device",
            "source": "IotCore",
            "target": "LocalMqtt"
        }
    }
}
```
`noLocal` is only supported for routes where the `source` is `LocalMqtt`.  
Default: false  
retainAsPublished  
(Optional) When enabled, messages forwarded by the bridge have the same `retain` flag as messages published to the broker for that route.  
`retainAsPublished` is only supported for routes where the `source` is `LocalMqtt`.  
Default: false

mqtt  
(Optional) MQTT protocol settings for communicating with the local broker.    
version  
(Optional) The MQTT protocol version used by the bridge to communicate with the local broker. Must be the same as the MQTT version selected in the nucleus configuration.   
Choose from the following:   
+ `mqtt3`
+ `mqtt5`
You must deploy an MQTT broker when the `source` or `target` field of the `mqttTopicMapping` object is set to `LocalMqtt`. If you choose the `mqtt5` option you must use the [MQTT 5 broker (EMQX)](mqtt-broker-emqx-component.md).  
Default: `mqtt3`  
ackTimeoutSeconds  
(Optional) Time interval to wait for PUBACK, SUBACK, or UNSUBACK packets before failing the operation.  
Default: 60  
connAckTimeoutMs  
(Optional) Time interval to wait for a CONNACK packet before shutting down the connection.  
Default: 20000 (20 seconds)  
pingTimeoutMs  
(Optional) The amount of time in milliseconds that the bridge waits to receive a PINGACK message from the local broker. If the wait exceeds the timeout, the bridge closes then reopens the MQTT connection. This value must be less than `keepAliveTimeoutSeconds`.  
Default: 30000 (30 seconds)  
keepAliveTimeoutSeconds  
(Optional) The amount of time in seconds between each PING message that the bridge sends to keep the MQTT connection alive. This value must be greater than `pingTimeoutMs`.  
Default: 60  
maxReconnectDelayMs  
(Optional) The maximum amount of time in seconds for MQTT to reconnect.  
Default: 30000 (30 seconds)  
minReconnectDelayMs  
(Optional) The minimum amount of time in seconds for MQTT to reconnect.  
receiveMaximum  
(Optional) The maximum number of unacknowledged QoS1 packets the bridge can send.  
Default: 100  
maximumPacketSize  
The maximum number of bytes the client will accept for an MQTT packet.  
Default: null (No limit)  
sessionExpiryInterval  
(Optional) The amount of time in seconds you can request for a session to last between the bridge and the local broker.  
Default: 4294967295 (session never expires)

`brokerUri`  <a name="mqtt-bridge-component-configuration-broker-uri"></a>
(Optional) The URI of the local MQTT broker. You must specify this parameter if you configure the MQTT broker to use a different port than the default port 8883. Use the following format, and replace *port* with the port where the MQTT broker operates: `ssl://localhost:port`.  
Default: `ssl://localhost:8883`

startupTimeoutSeconds  
(Optional) The maximum of time in seconds for the component to start. The component's state changes to `BROKEN` if it exceeds this timeout.  
Default: `120`

**Example: Configuration merge update**  <a name="mqtt-bridge-component-configuration-example-with-prefix"></a>
The following example configuration update specifies the following:  
+ Relay messages from client devices to AWS IoT Core on topics that match the `clients/+/hello/world` topic filter.
+ Relay messages from client devices to local publish/subscribe on topics that match the `clients/+/detections` topic filter, and add the `events/input/` prefix to the target topic. The resulting target topic matches the `events/input/clients/+/detections` topic filter.
+ Relay messages from client devices to AWS IoT Core on topics that match the `clients/+/status` topic filter, and add the `$aws/rules/StatusUpdateRule/` prefix to the target topic. This example relays these messages directly to an [AWS IoT rule](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rules.html) named `StatusUpdateRule` to reduce costs using [Basic Ingest](https://docs.aws.amazon.com/iot/latest/developerguide/iot-basic-ingest.html).

```
{
  "mqttTopicMapping": {
    "ClientDeviceHelloWorld": {
      "topic": "clients/+/hello/world",
      "source": "LocalMqtt",
      "target": "IotCore"
    },
    "ClientDeviceEvents": {
      "topic": "clients/+/detections",
      "targetTopicPrefix": "events/input/",
      "source": "LocalMqtt",
      "target": "Pubsub"
    },
    "ClientDeviceCloudStatusUpdate": {
      "topic": "clients/+/status",
      "targetTopicPrefix": "$aws/rules/StatusUpdateRule/",
      "source": "LocalMqtt",
      "target": "IotCore"
    }
  }
}
```

**Example: Configuring MQTT 5**  
The following example configuration updates the following:  
+ Enables the bridge to use the MQTT 5 protocol with the local broker.
+ Configures MQTT retain as published setting for the `ClientDeviceHelloWorld` topic mapping.

```
{
  "mqttTopicMapping": {
    "ClientDeviceHelloWorld": {
      "topic": "clients/+/hello/world",
      "source": "LocalMqtt",
      "target": "IotCore"
    }
  },
  "mqtt5RouteOptions": {
    "ClientDeviceHelloWorld": {
      "retainAsPublished": true
    }
  },
  "mqtt": {
    "version": "mqtt5"
  }
}
```

------
#### [ 2.2.6 ]

`mqttTopicMapping`  
<a name="mqtt-bridge-component-configuration-mqtt-topic-mapping-description"></a>The topic mappings that you want to bridge. This component subscribes to messages on the source topic and publishes the messages that it receives to the destination topic. Each topic mapping defines the topic, source type, and destination type.  
This object contains the following information:    
`topicMappingNameKey`  
<a name="mqtt-bridge-component-configuration-mqtt-topic-mapping-name-key-description"></a>The name of this topic mapping. Replace *topicMappingNameKey* with a name that helps you identify this topic mapping.  
This object contains the following information:    
`topic`  
The topic or topic filter to bridge between the source and target brokers.  
You can use the `+` and `#` MQTT topic wildcards to relay messages on all topics that match a topic filter. For more information, see [MQTT topics](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html) in the *AWS IoT Core Developer Guide*.  
To use MQTT topic wildcards with the `Pubsub` source broker, you must use v2.6.0 or later of the [Greengrass nucleus component](greengrass-nucleus-component.md).  
`targetTopicPrefix`  
The prefix to add to the target topic when this component relays the message.  
`source`  <a name="mqtt-bridge-component-configuration-mqtt-topic-mapping-source"></a>
The source message broker. Choose from the following options:  <a name="mqtt-bridge-component-configuration-topic-types"></a>
+ `LocalMqtt` – The local MQTT broker where client devices communicate.
+ `Pubsub` – The local Greengrass publish/subscribe message broker.
+ `IotCore` – The AWS IoT Core MQTT message broker.
**Note**  <a name="mqtt-bridge-component-iotcore-qos-1-note"></a>
The MQTT bridge uses QoS 1 to publish and subscribe to AWS IoT Core, even when a client device uses QoS 0 to publish and subscribe to the local MQTT broker. As a result, you might observe additional latency when you relay MQTT messages from client devices on the local MQTT broker to AWS IoT Core. For more information about MQTT configuration on core devices, see [Configure MQTT timeouts and cache settings](configure-greengrass-core-v2.md#configure-mqtt).
`source` and `target` must be different.  
`target`  <a name="mqtt-bridge-component-configuration-mqtt-topic-mapping-target"></a>
The target message broker. Choose from the following options:  <a name="mqtt-bridge-component-configuration-topic-types"></a>
+ `LocalMqtt` – The local MQTT broker where client devices communicate.
+ `Pubsub` – The local Greengrass publish/subscribe message broker.
+ `IotCore` – The AWS IoT Core MQTT message broker.
**Note**  <a name="mqtt-bridge-component-iotcore-qos-1-note"></a>
The MQTT bridge uses QoS 1 to publish and subscribe to AWS IoT Core, even when a client device uses QoS 0 to publish and subscribe to the local MQTT broker. As a result, you might observe additional latency when you relay MQTT messages from client devices on the local MQTT broker to AWS IoT Core. For more information about MQTT configuration on core devices, see [Configure MQTT timeouts and cache settings](configure-greengrass-core-v2.md#configure-mqtt).
`source` and `target` must be different.

`brokerUri`  <a name="mqtt-bridge-component-configuration-broker-uri"></a>
(Optional) The URI of the local MQTT broker. You must specify this parameter if you configure the MQTT broker to use a different port than the default port 8883. Use the following format, and replace *port* with the port where the MQTT broker operates: `ssl://localhost:port`.  
Default: `ssl://localhost:8883`

startupTimeoutSeconds  
(Optional) The maximum of time in seconds for the component to start. The component's state changes to `BROKEN` if it exceeds this timeout.  
Default: `120`

**Example: Configuration merge update**  <a name="mqtt-bridge-component-configuration-example-with-prefix"></a>
The following example configuration update specifies the following:  
+ Relay messages from client devices to AWS IoT Core on topics that match the `clients/+/hello/world` topic filter.
+ Relay messages from client devices to local publish/subscribe on topics that match the `clients/+/detections` topic filter, and add the `events/input/` prefix to the target topic. The resulting target topic matches the `events/input/clients/+/detections` topic filter.
+ Relay messages from client devices to AWS IoT Core on topics that match the `clients/+/status` topic filter, and add the `$aws/rules/StatusUpdateRule/` prefix to the target topic. This example relays these messages directly to an [AWS IoT rule](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rules.html) named `StatusUpdateRule` to reduce costs using [Basic Ingest](https://docs.aws.amazon.com/iot/latest/developerguide/iot-basic-ingest.html).

```
{
  "mqttTopicMapping": {
    "ClientDeviceHelloWorld": {
      "topic": "clients/+/hello/world",
      "source": "LocalMqtt",
      "target": "IotCore"
    },
    "ClientDeviceEvents": {
      "topic": "clients/+/detections",
      "targetTopicPrefix": "events/input/",
      "source": "LocalMqtt",
      "target": "Pubsub"
    },
    "ClientDeviceCloudStatusUpdate": {
      "topic": "clients/+/status",
      "targetTopicPrefix": "$aws/rules/StatusUpdateRule/",
      "source": "LocalMqtt",
      "target": "IotCore"
    }
  }
}
```

------
#### [ 2.2.0 - 2.2.5 ]

`mqttTopicMapping`  
<a name="mqtt-bridge-component-configuration-mqtt-topic-mapping-description"></a>The topic mappings that you want to bridge. This component subscribes to messages on the source topic and publishes the messages that it receives to the destination topic. Each topic mapping defines the topic, source type, and destination type.  
This object contains the following information:    
`topicMappingNameKey`  
<a name="mqtt-bridge-component-configuration-mqtt-topic-mapping-name-key-description"></a>The name of this topic mapping. Replace *topicMappingNameKey* with a name that helps you identify this topic mapping.  
This object contains the following information:    
`topic`  
The topic or topic filter to bridge between the source and target brokers.  
You can use the `+` and `#` MQTT topic wildcards to relay messages on all topics that match a topic filter. For more information, see [MQTT topics](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html) in the *AWS IoT Core Developer Guide*.  
To use MQTT topic wildcards with the `Pubsub` source broker, you must use v2.6.0 or later of the [Greengrass nucleus component](greengrass-nucleus-component.md).  
`targetTopicPrefix`  
The prefix to add to the target topic when this component relays the message.  
`source`  <a name="mqtt-bridge-component-configuration-mqtt-topic-mapping-source"></a>
The source message broker. Choose from the following options:  <a name="mqtt-bridge-component-configuration-topic-types"></a>
+ `LocalMqtt` – The local MQTT broker where client devices communicate.
+ `Pubsub` – The local Greengrass publish/subscribe message broker.
+ `IotCore` – The AWS IoT Core MQTT message broker.
**Note**  <a name="mqtt-bridge-component-iotcore-qos-1-note"></a>
The MQTT bridge uses QoS 1 to publish and subscribe to AWS IoT Core, even when a client device uses QoS 0 to publish and subscribe to the local MQTT broker. As a result, you might observe additional latency when you relay MQTT messages from client devices on the local MQTT broker to AWS IoT Core. For more information about MQTT configuration on core devices, see [Configure MQTT timeouts and cache settings](configure-greengrass-core-v2.md#configure-mqtt).
`source` and `target` must be different.  
`target`  <a name="mqtt-bridge-component-configuration-mqtt-topic-mapping-target"></a>
The target message broker. Choose from the following options:  <a name="mqtt-bridge-component-configuration-topic-types"></a>
+ `LocalMqtt` – The local MQTT broker where client devices communicate.
+ `Pubsub` – The local Greengrass publish/subscribe message broker.
+ `IotCore` – The AWS IoT Core MQTT message broker.
**Note**  <a name="mqtt-bridge-component-iotcore-qos-1-note"></a>
The MQTT bridge uses QoS 1 to publish and subscribe to AWS IoT Core, even when a client device uses QoS 0 to publish and subscribe to the local MQTT broker. As a result, you might observe additional latency when you relay MQTT messages from client devices on the local MQTT broker to AWS IoT Core. For more information about MQTT configuration on core devices, see [Configure MQTT timeouts and cache settings](configure-greengrass-core-v2.md#configure-mqtt).
`source` and `target` must be different.

`brokerUri`  <a name="mqtt-bridge-component-configuration-broker-uri"></a>
(Optional) The URI of the local MQTT broker. You must specify this parameter if you configure the MQTT broker to use a different port than the default port 8883. Use the following format, and replace *port* with the port where the MQTT broker operates: `ssl://localhost:port`.  
Default: `ssl://localhost:8883`

**Example: Configuration merge update**  <a name="mqtt-bridge-component-configuration-example-with-prefix"></a>
The following example configuration update specifies the following:  
+ Relay messages from client devices to AWS IoT Core on topics that match the `clients/+/hello/world` topic filter.
+ Relay messages from client devices to local publish/subscribe on topics that match the `clients/+/detections` topic filter, and add the `events/input/` prefix to the target topic. The resulting target topic matches the `events/input/clients/+/detections` topic filter.
+ Relay messages from client devices to AWS IoT Core on topics that match the `clients/+/status` topic filter, and add the `$aws/rules/StatusUpdateRule/` prefix to the target topic. This example relays these messages directly to an [AWS IoT rule](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rules.html) named `StatusUpdateRule` to reduce costs using [Basic Ingest](https://docs.aws.amazon.com/iot/latest/developerguide/iot-basic-ingest.html).

```
{
  "mqttTopicMapping": {
    "ClientDeviceHelloWorld": {
      "topic": "clients/+/hello/world",
      "source": "LocalMqtt",
      "target": "IotCore"
    },
    "ClientDeviceEvents": {
      "topic": "clients/+/detections",
      "targetTopicPrefix": "events/input/",
      "source": "LocalMqtt",
      "target": "Pubsub"
    },
    "ClientDeviceCloudStatusUpdate": {
      "topic": "clients/+/status",
      "targetTopicPrefix": "$aws/rules/StatusUpdateRule/",
      "source": "LocalMqtt",
      "target": "IotCore"
    }
  }
}
```

------
#### [ 2.1.x ]

`mqttTopicMapping`  <a name="mqtt-bridge-component-configuration-mqtt-topic-mapping"></a>
<a name="mqtt-bridge-component-configuration-mqtt-topic-mapping-description"></a>The topic mappings that you want to bridge. This component subscribes to messages on the source topic and publishes the messages that it receives to the destination topic. Each topic mapping defines the topic, source type, and destination type.  
This object contains the following information:    
`topicMappingNameKey`  
<a name="mqtt-bridge-component-configuration-mqtt-topic-mapping-name-key-description"></a>The name of this topic mapping. Replace *topicMappingNameKey* with a name that helps you identify this topic mapping.  
This object contains the following information:    
`topic`  
The topic or topic filter to bridge between the source and target brokers.  
If you specify the `LocalMqtt` or `IotCore` source broker, you can use the `+` and `#` MQTT topic wildcards to relay messages on all topics that match a topic filter. For more information, see [MQTT topics](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html) in the *AWS IoT Core Developer Guide*.  
`source`  <a name="mqtt-bridge-component-configuration-mqtt-topic-mapping-source"></a>
The source message broker. Choose from the following options:  <a name="mqtt-bridge-component-configuration-topic-types"></a>
+ `LocalMqtt` – The local MQTT broker where client devices communicate.
+ `Pubsub` – The local Greengrass publish/subscribe message broker.
+ `IotCore` – The AWS IoT Core MQTT message broker.
**Note**  <a name="mqtt-bridge-component-iotcore-qos-1-note"></a>
The MQTT bridge uses QoS 1 to publish and subscribe to AWS IoT Core, even when a client device uses QoS 0 to publish and subscribe to the local MQTT broker. As a result, you might observe additional latency when you relay MQTT messages from client devices on the local MQTT broker to AWS IoT Core. For more information about MQTT configuration on core devices, see [Configure MQTT timeouts and cache settings](configure-greengrass-core-v2.md#configure-mqtt).
`source` and `target` must be different.  
`target`  <a name="mqtt-bridge-component-configuration-mqtt-topic-mapping-target"></a>
The target message broker. Choose from the following options:  <a name="mqtt-bridge-component-configuration-topic-types"></a>
+ `LocalMqtt` – The local MQTT broker where client devices communicate.
+ `Pubsub` – The local Greengrass publish/subscribe message broker.
+ `IotCore` – The AWS IoT Core MQTT message broker.
**Note**  <a name="mqtt-bridge-component-iotcore-qos-1-note"></a>
The MQTT bridge uses QoS 1 to publish and subscribe to AWS IoT Core, even when a client device uses QoS 0 to publish and subscribe to the local MQTT broker. As a result, you might observe additional latency when you relay MQTT messages from client devices on the local MQTT broker to AWS IoT Core. For more information about MQTT configuration on core devices, see [Configure MQTT timeouts and cache settings](configure-greengrass-core-v2.md#configure-mqtt).
`source` and `target` must be different.

`brokerUri`  <a name="mqtt-bridge-component-configuration-broker-uri"></a>
(Optional) The URI of the local MQTT broker. You must specify this parameter if you configure the MQTT broker to use a different port than the default port 8883. Use the following format, and replace *port* with the port where the MQTT broker operates: `ssl://localhost:port`.  
Default: `ssl://localhost:8883`

**Example: Configuration merge update**  <a name="mqtt-bridge-component-configuration-example-no-prefix"></a>
The following example configuration update specifies to relay messages from client devices to AWS IoT Core on the `clients/MyClientDevice1/hello/world` and `clients/MyClientDevice2/hello/world` topics.  

```
{
  "mqttTopicMapping": {
    "ClientDevice1HelloWorld": {
      "topic": "clients/MyClientDevice1/hello/world",
      "source": "LocalMqtt",
      "target": "IotCore"
    },
    "ClientDevice2HelloWorld": {
      "topic": "clients/MyClientDevice2/hello/world",
      "source": "LocalMqtt",
      "target": "IotCore"
    }
  }
}
```

------
#### [ 2.0.x ]

`mqttTopicMapping`  <a name="mqtt-bridge-component-configuration-mqtt-topic-mapping"></a>
<a name="mqtt-bridge-component-configuration-mqtt-topic-mapping-description"></a>The topic mappings that you want to bridge. This component subscribes to messages on the source topic and publishes the messages that it receives to the destination topic. Each topic mapping defines the topic, source type, and destination type.  
This object contains the following information:    
`topicMappingNameKey`  
<a name="mqtt-bridge-component-configuration-mqtt-topic-mapping-name-key-description"></a>The name of this topic mapping. Replace *topicMappingNameKey* with a name that helps you identify this topic mapping.  
This object contains the following information:    
`topic`  
The topic or topic filter to bridge between the source and target brokers.  
If you specify the `LocalMqtt` or `IotCore` source broker, you can use the `+` and `#` MQTT topic wildcards to relay messages on all topics that match a topic filter. For more information, see [MQTT topics](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html) in the *AWS IoT Core Developer Guide*.  
`source`  <a name="mqtt-bridge-component-configuration-mqtt-topic-mapping-source"></a>
The source message broker. Choose from the following options:  <a name="mqtt-bridge-component-configuration-topic-types"></a>
+ `LocalMqtt` – The local MQTT broker where client devices communicate.
+ `Pubsub` – The local Greengrass publish/subscribe message broker.
+ `IotCore` – The AWS IoT Core MQTT message broker.
**Note**  <a name="mqtt-bridge-component-iotcore-qos-1-note"></a>
The MQTT bridge uses QoS 1 to publish and subscribe to AWS IoT Core, even when a client device uses QoS 0 to publish and subscribe to the local MQTT broker. As a result, you might observe additional latency when you relay MQTT messages from client devices on the local MQTT broker to AWS IoT Core. For more information about MQTT configuration on core devices, see [Configure MQTT timeouts and cache settings](configure-greengrass-core-v2.md#configure-mqtt).
`source` and `target` must be different.  
`target`  <a name="mqtt-bridge-component-configuration-mqtt-topic-mapping-target"></a>
The target message broker. Choose from the following options:  <a name="mqtt-bridge-component-configuration-topic-types"></a>
+ `LocalMqtt` – The local MQTT broker where client devices communicate.
+ `Pubsub` – The local Greengrass publish/subscribe message broker.
+ `IotCore` – The AWS IoT Core MQTT message broker.
**Note**  <a name="mqtt-bridge-component-iotcore-qos-1-note"></a>
The MQTT bridge uses QoS 1 to publish and subscribe to AWS IoT Core, even when a client device uses QoS 0 to publish and subscribe to the local MQTT broker. As a result, you might observe additional latency when you relay MQTT messages from client devices on the local MQTT broker to AWS IoT Core. For more information about MQTT configuration on core devices, see [Configure MQTT timeouts and cache settings](configure-greengrass-core-v2.md#configure-mqtt).
`source` and `target` must be different.

**Example: Configuration merge update**  <a name="mqtt-bridge-component-configuration-example-no-prefix"></a>
The following example configuration update specifies to relay messages from client devices to AWS IoT Core on the `clients/MyClientDevice1/hello/world` and `clients/MyClientDevice2/hello/world` topics.  

```
{
  "mqttTopicMapping": {
    "ClientDevice1HelloWorld": {
      "topic": "clients/MyClientDevice1/hello/world",
      "source": "LocalMqtt",
      "target": "IotCore"
    },
    "ClientDevice2HelloWorld": {
      "topic": "clients/MyClientDevice2/hello/world",
      "source": "LocalMqtt",
      "target": "IotCore"
    }
  }
}
```

------

## Local log file


This component uses the same log file as the [Greengrass nucleus](greengrass-nucleus-component.md) component.

------
#### [ Linux ]

```
/greengrass/v2/logs/greengrass.log
```

------
#### [ Windows ]

```
C:\greengrass\v2\logs\greengrass.log
```

------

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the path to the AWS IoT Greengrass root folder.

------
#### [ Linux ]

  ```
  sudo tail -f /greengrass/v2/logs/greengrass.log
  ```

------
#### [ Windows (PowerShell) ]

  ```
  Get-Content C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
  ```

------

## Changelog


The following table describes the changes in each version of the component.


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.3.2  |  Version updated for [client device auth](client-device-auth-component.md) version 2.5.0 release.  | 
| 2.3.1 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/mqtt-bridge-component.html)  | 
| 2.3.0 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/mqtt-bridge-component.html)  | 
|  2.2.6  |  <a name="changelog-mqtt-bridge-2.2.6"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/mqtt-bridge-component.html)  | 
|  2.2.5  |  Version updated for [client device auth](client-device-auth-component.md) version 2.4.0 release.  | 
|  2.2.4  |  Version updated for Greengrass [client device auth](client-device-auth-component.md) version 2.3.0 release.  | 
|  2.2.3  |  This version contains bug fixes and improvements.  | 
|  2.2.2  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/mqtt-bridge-component.html)  | 
|  2.2.1  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/mqtt-bridge-component.html)  | 
|  2.2.0  |  <a name="changelog-mqtt-bridge-2.2.0"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/mqtt-bridge-component.html)  | 
|  2.1.1  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/mqtt-bridge-component.html)  | 
|  2.1.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/mqtt-bridge-component.html)  | 
|  2.0.1  |  This version includes bug fixes and improvements.  | 
|  2.0.0  |  Initial version.  | 

# MQTT 3.1.1 broker (Moquette)
Moquette MQTT 3.1.1 broker v2.3.6 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/mqtt-broker-moquette-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/mqtt-broker-moquette-component.html)

Moquette MQTT 3.1.1 broker component v2.3.6 is available. This version includes general bug fixes and improvements.Moquette MQTT 3.1.1 broker v2.3.5 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/mqtt-broker-moquette-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/mqtt-broker-moquette-component.html)

Moquette MQTT 3.1.1 broker component v2.3.5 is available. This version updates Moquette to version 0.17.Moquette MQTT 3.1.1 broker v2.3.4 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/mqtt-broker-moquette-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/mqtt-broker-moquette-component.html)

Moquette MQTT 3.1.1 broker component v2.3.4 is available.

The Moquette MQTT broker component (`aws.greengrass.clientdevices.mqtt.Moquette`) handles MQTT messages between client devices and a Greengrass core device. This component provides a modified version of the [Moquette MQTT broker](https://github.com/moquette-io/moquette). Deploy this MQTT broker to run a lightweight MQTT broker. For more information about how to choose an MQTT broker, see [Choose an MQTT broker](choose-local-mqtt-broker.md).

This broker implements the MQTT 3.1.1 protocol. It includes support for QoS 0, QoS 1, QoS 2 retained messages, last will messages, and persistent sessions.

**Note**  <a name="client-device-component-context"></a>
Client devices are local IoT devices that connect to a Greengrass core device to send MQTT messages and data to process. For more information, see [Interact with local IoT devices](interact-with-local-iot-devices.md).

**Topics**
+ [

## Versions
](#mqtt-broker-moquette-component-versions)
+ [

## Type
](#mqtt-broker-moquette-component-type)
+ [

## Operating system
](#mqtt-broker-moquette-component-os-support)
+ [

## Requirements
](#mqtt-broker-moquette-component-requirements)
+ [

## Dependencies
](#mqtt-broker-moquette-component-dependencies)
+ [

## Configuration
](#mqtt-broker-moquette-component-configuration)
+ [

## Local log file
](#mqtt-broker-moquette-component-log-file)
+ [

## Changelog
](#mqtt-broker-moquette-component-changelog)

## Versions


This component has the following versions:
+ 2.3.x
+ 2.2.x
+ 2.1.x
+ 2.0.x

## Type


<a name="public-component-type-plugin-para1"></a>This component is a plugin component (`aws.greengrass.plugin`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs this component in the same Java Virtual Machine (JVM) as the nucleus. The nucleus restarts when you change this component's version on the core device.

<a name="public-component-type-plugin-para2"></a>This component uses the same log file as the Greengrass nucleus. For more information, see [Monitor AWS IoT Greengrass logs](monitor-logs.md).

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on core devices that run the following operating systems:
+ Linux
+ Windows

## Requirements


This component has the following requirements:
+ The core device must be able to accept connections on the port where the MQTT broker operates. This component runs the MQTT broker on port 8883 by default. You can specify a different port when you configure this component.

  <a name="mqtt-broker-configuration-mqtt-bridge-requirement"></a>If you specify a different port, and you use the [MQTT bridge component](mqtt-bridge-component.md) to relay MQTT messages to other brokers, you must use MQTT bridge v2.1.0 or later. Configure it to use the port where the MQTT broker operates.

  <a name="mqtt-broker-configuration-ip-detector-requirement"></a>If you specify a different port, and you use the [IP detector component](ip-detector-component.md) to manage MQTT broker endpoints, you must use IP detector v2.1.0 or later. Configure it to report the port where the MQTT broker operates.
+ The Moquette MQTT broker component is supported to run in a VPC.

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#mqtt-broker-moquette-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

------
#### [ 2.3.7 ]

The following table lists the dependencies for version 2.3.7 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Client device auth](client-device-auth-component.md) | >=2.2.0 <2.6.0 | Hard | 

------
#### [ 2.3.2 – 2.3.6 ]

The following table lists the dependencies for versions 2.3.2 through 2.3.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Client device auth](client-device-auth-component.md) | >=2.2.0 <2.5.0 | Hard | 

------
#### [ 2.3.0 and 2.3.1 ]

The following table lists the dependencies for versions 2.3.0 and 2.3.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Client device auth](client-device-auth-component.md) | >=2.2.0 <2.4.0 | Hard | 

------
#### [ 2.2.0 ]

The following table lists the dependencies for version 2.2.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Client device auth](client-device-auth-component.md) | >=2.2.0 <2.3.0 | Hard | 

------
#### [ 2.1.0 ]

The following table lists the dependencies for version 2.1.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Client device auth](client-device-auth-component.md) | >=2.0.0 <2.2.0 | Hard | 

------
#### [ 2.0.0 - 2.0.2 ]

The following table lists the dependencies for versions 2.0.0 through 2.0.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Client device auth](client-device-auth-component.md) | >=2.0.0 <2.1.0 | Hard | 

------

For more information about component dependencies, see the [component recipe reference](component-recipe-reference.md#recipe-reference-component-dependencies).

## Configuration


This component provides the following configuration parameters that you can customize when you deploy the component.

`moquette`  
(Optional) The [Moquette MQTT broker](https://github.com/moquette-io/moquette) configuration to use. You can configure a subset of Moqeutte configuration options in this component. For more information, see the inline comments in the [Moquette configuration file](https://github.com/moquette-io/moquette/blob/main/distribution/src/main/resources/moquette.conf).  
This object contains the following information:    
`ssl_port`  
(Optional) The port where the MQTT broker operates.  
<a name="mqtt-broker-configuration-mqtt-bridge-requirement"></a>If you specify a different port, and you use the [MQTT bridge component](mqtt-bridge-component.md) to relay MQTT messages to other brokers, you must use MQTT bridge v2.1.0 or later. Configure it to use the port where the MQTT broker operates.  
<a name="mqtt-broker-configuration-ip-detector-requirement"></a>If you specify a different port, and you use the [IP detector component](ip-detector-component.md) to manage MQTT broker endpoints, you must use IP detector v2.1.0 or later. Configure it to report the port where the MQTT broker operates.
Default: `8883`  
`host`  
(Optional) The interface where the MQTT broker binds. For example, you might change this parameter so that the MQTT broker binds only to a specific local network.  
Default: `0.0.0.0` (binds to all network interfaces)

startupTimeoutSeconds  
(Optional) The maximum of time in seconds for the component to start. The component's state changes to `BROKEN` if it exceeds this timeout.  
Default: `120`

**Example: Configuration merge update**  
The following example configuration specifies to operate the MQTT broker on port 443.  

```
{
  "moquette": {
    "ssl_port": "443"
  }
}
```

## Local log file


This component uses the same log file as the [Greengrass nucleus](greengrass-nucleus-component.md) component.

------
#### [ Linux ]

```
/greengrass/v2/logs/greengrass.log
```

------
#### [ Windows ]

```
C:\greengrass\v2\logs\greengrass.log
```

------

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the path to the AWS IoT Greengrass root folder.

------
#### [ Linux ]

  ```
  sudo tail -f /greengrass/v2/logs/greengrass.log
  ```

------
#### [ Windows (PowerShell) ]

  ```
  Get-Content C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
  ```

------

## Changelog


The following table describes the changes in each version of the component.


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.3.7  |  Version updated for [client device auth](client-device-auth-component.md) version 2.5.0 release.  | 
|  2.3.6  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/mqtt-broker-moquette-component.html)  | 
|  2.3.5  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/mqtt-broker-moquette-component.html)  | 
|  2.3.4  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/mqtt-broker-moquette-component.html)  | 
|  2.3.3  |  <a name="changelog-mqtt-broker-moquette-2.3.3"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/mqtt-broker-moquette-component.html)  | 
|  2.3.2  |  Version updated for [client device auth](client-device-auth-component.md) version 2.4.0 release.  | 
|  2.3.1  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/mqtt-broker-moquette-component.html)  | 
|  2.3.0  |  Adds support for certificate chains.  | 
|  2.2.0  |  Version updated for [client device auth](client-device-auth-component.md) version 2.2.0 release.  | 
|  2.1.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/mqtt-broker-moquette-component.html)  | 
|  2.0.2  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/mqtt-broker-moquette-component.html)  | 
|  2.0.1  |  Version updated for Greengrass nucleus version 2.4.0 release.  | 
|  2.0.0  |  Initial version.  | 

# MQTT 5 broker (EMQX)


The EMQX MQTT broker component (`aws.greengrass.clientdevices.mqtt.EMQX`) handles MQTT messages between client devices and a Greengrass core device. This component provides a modified version of the [EMQX MQTT 5.0 broker](https://www.emqx.com/en/mqtt/mqtt5). Deploy this MQTT broker to use MQTT 5 features in communication between client devices and a core device. For more information about how to choose an MQTT broker, see [Choose an MQTT broker](choose-local-mqtt-broker.md).

This broker implements the MQTT 5.0 protocol. It includes support for session and message expiration intervals, user properties, shared subscriptions, topic aliases, and more. MQTT 5 is backwards compatible with MQTT 3.1.1, so if you run the [Moquette MQTT 3.1.1 broker](mqtt-broker-moquette-component.md), you can replace it with the EMQX MQTT 5 broker, and client devices can continue to connect and operate as usual.

<a name="note-local-mqtt-broker-mqtt-5-features"></a>

**Note**  <a name="client-device-component-context"></a>
Client devices are local IoT devices that connect to a Greengrass core device to send MQTT messages and data to process. For more information, see [Interact with local IoT devices](interact-with-local-iot-devices.md).

**Topics**
+ [

## Versions
](#mqtt-broker-emqx-component-versions)
+ [

## Type
](#mqtt-broker-emqx-component-type)
+ [

## Operating system
](#mqtt-broker-emqx-component-os-support)
+ [

## Requirements
](#mqtt-broker-emqx-component-requirements)
+ [

## Dependencies
](#mqtt-broker-emqx-component-dependencies)
+ [

## Configuration
](#mqtt-broker-emqx-component-configuration)
+ [

## Local log file
](#mqtt-broker-emqx-component-log-file)
+ [

## Licenses
](#mqtt-broker-emqx-component-licenses)
+ [

## Changelog
](#mqtt-broker-emqx-component-changelog)

## Versions


This component has the following versions:
+ 2.0.x
+ 1.2.x
+ 1.1.x
+ 1.0.x

## Type


<a name="public-component-type-generic"></a>This <a name="public-component-type-generic-phrase"></a>component is a generic component (`aws.greengrass.generic`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs the component's lifecycle scripts.

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on core devices that run the following operating systems:
+ Linux
+ Windows

## Requirements


This component has the following requirements:
+ The core device must be able to accept connections on the port where the MQTT broker operates. This component runs the MQTT broker on port 8883 by default. You can specify a different port when you configure this component.

  <a name="mqtt-broker-configuration-mqtt-bridge-requirement"></a>If you specify a different port, and you use the [MQTT bridge component](mqtt-bridge-component.md) to relay MQTT messages to other brokers, you must use MQTT bridge v2.1.0 or later. Configure it to use the port where the MQTT broker operates.

  <a name="mqtt-broker-configuration-ip-detector-requirement"></a>If you specify a different port, and you use the [IP detector component](ip-detector-component.md) to manage MQTT broker endpoints, you must use IP detector v2.1.0 or later. Configure it to report the port where the MQTT broker operates.
+ On Linux core devices, Docker installed and configured on the core device:
  + <a name="docker-engine-requirement"></a>[Docker Engine](https://docs.docker.com/engine/) 1.9.1 or later installed on the Greengrass core device. Version 20.10 is the latest version that is verified to work with the AWS IoT Greengrass Core software. You must install Docker directly on the core device before you deploy components that run Docker containers.
  + <a name="docker-daemon-requirement"></a>The Docker daemon started and running on the core device before you deploy this component. 
  + The system user that runs this component must have root or administrator permissions. Alternatively, you can run this component as a system user in the `docker` group and configure this component's `requiresPrivileges` option to `false` to run the EQMX MQTT broker without privileges.
+ The EMQX MQTT broker component is supported to run in a VPC.
+ The EMQX MQTT broker component is not supported on the `armv7` platform.

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#mqtt-broker-emqx-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

------
#### [ 2.0.2 – 2.0.3 ]

The following table lists the dependencies for versions 2.0.2 and 2.0.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Client device auth](client-device-auth-component.md) | >=2.2.0 <2.6.0 | Soft | 

------
#### [ 2.0.1 ]

The following table lists the dependencies for version 2.0.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Client device auth](client-device-auth-component.md) | >=2.2.0 <2.6.0 | Hard | 

------
#### [ 2.0.0 ]

The following table lists the dependencies for version 2.0.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Client device auth](client-device-auth-component.md) | >=2.2.0 <2.5.0 | Hard | 

------
#### [ 1.2.2 – 1.2.3 ]

The following table lists the dependencies for versions 1.2.2 to 1.2.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Client device auth](client-device-auth-component.md) | >=2.2.0 <2.5.0 | Hard | 

------
#### [ 1.2.0 and 1.2.1 ]

The following table lists the dependencies for versions 1.2.0 and 1.2.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Client device auth](client-device-auth-component.md) | >=2.2.0 <2.4.0 | Hard | 

------
#### [ 1.0.0 and 1.1.0 ]

The following table lists the dependencies for versions 1.0.0 and 1.1.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Client device auth](client-device-auth-component.md) | >=2.2.0 <2.3.0 | Hard | 

------

For more information about component dependencies, see the [component recipe reference](component-recipe-reference.md#recipe-reference-component-dependencies).

## Configuration


------
#### [ 2.0.0 - 2.0.3 ]

This component provides the following configuration parameters that you can customize when you deploy the component.

**Important**  
If you use version 2 of the MQTT 5 broker (EMQX) component, you must update your configuration file. Version 1 configuration files do not work with version 2.

emqxConfig  
 (Optional) The [EMQX MQTT broker](https://www.emqx.io/docs/en/v5.1/configuration/configuration.html) configuration to use. You can set EMQX configuration options in this component.  
When you use the EMQX broker, Greengrass uses a default configuration. This configuration is used unless you modify it using this field.  
Modifying the following configuration settings causes the EMQX broker component to restart. Other configuration changes apply without restarting the component.  
+ `emqxConfig/cluster`
+ `emqxConfig/node`
+ `emqxConfig/rpc`
`aws.greengrass.clientdevices.mqtt.EMQX` allows you to configure security-sensitive options. These include TLS settings, authentication, and authorization providers. We recommended the default configuration that uses mutual TLS authentication and the Greengrass client device auth provider.

**Example: Default configuration**  
The following example shows the defaults set for the MQTT 5 (EMQX) broker. You can override these settings using the `emqxConfig` configuration setting.  

```
{
  "authorization": {
    "no_match": "deny",
    "sources": []
  },
  "node": {
    "cookie": "<placeholder>"
  }, 
  "listeners": {
     "ssl": {
       "default": {
         "ssl_options": {
           "keyfile": "{work:path}\\data\\key.pem",
           "certfile": "{work:path}\\data\\cert.pem",
           "cacertfile": null,
           "verify": "verify_peer",
           "versions": ["tlsv1.3", "tlsv1.2"],
           "fail_if_no_peer_cert": true
         }
       }
     },
     "tcp": {
       "default": {
         "enabled": false
       }
     },
     "ws": {
       "default": {
         "enabled": false
       }
     },
     "wss": {
       "default": {
         "enabled": false
       }
     }
  },
  "plugins": {
    "states": [{"name_vsn": "gg-1.0.0", "enable": true}],
    "install_dir": "plugins"
  }
}
```

authMode  
(Optional) Sets the authorization provider for the broker. Can be one of the following values:  
+ `enabled` – (Default) Use the Greengrass authentication and authorization provider.
+ `bypass_on_failure` – Use the Greengrass authentication provider, then use any remaining authentication providers in the EMQX provider chain if Greengrass denies either authentication or authorization.
+ `bypass` – The Greengrass provider is disabled. Authentication and authorization is handled by the EMQX provider chain.

`requiresPrivilege`  
(Optional) On Linux core devices, you can specify to run the EMQX MQTT broker without root or administrator privileges. If you set this option to `false`, the system user that runs this component must be a member of the `docker` group.  
Default: `true`

`startupTimeoutSeconds`  
(Optional) The maximum of time in seconds for the EMQX MQTT broker to start. The component's state changes to `BROKEN` if it exceeds this timeout.  
Default: `90`

`ipcTimeoutSeconds`  
(Optional) The maximum of time in seconds for the component to wait for the Greengrass nucleus to respond to interprocess communication (IPC) requests. Increase this number if this component reports timeout errors when it checks if a client device is authorized.  
Default: `5`

`crtLogLevel`  
(Optional) The log level for the AWS Common Runtime (CRT) library.  
Defaults to the EMQX MQTT broker log level (`log.level` in `emqx`).

`restartIdentifier`  
(Optional) Configure this option to restart the EMQX MQTT broker. When this configuration value changes, this component restarts the MQTT broker. You can use this option to force client devices to disconnect.

`dockerOptions`  
(Optional) Configure this option only on Linux operating systems to add parameters to the Docker command line. For example, to map additional ports, use the `-p` Docker parameter:  

```
"-p 1883:1883"
```

**Example: Updating a v1.x configuration file to v2.x**  
The following example shows the changes necessary to update a v1.x configuration file to version 2.x.  
The version 1.x configuration file:  

```
{
    "emqx": {
        "listener.ssl.external": "443",
        "listener.ssl.external.max_connections": "1024000",
        "listener.ssl.external.max_conn_rate": "500",
        "listener.ssl.external.rate_limit": "50KB,5s",
        "listener.ssl.external.handshake_timeout": "15s",
        "log.level": "warning"
    },
    "mergeConfigurationFiles": {
        "etc/plugins/aws_greengrass_emqx_auth.conf": "auth_mode=enabled\n use_greengrass_managed_certificates=true\n"
    }
}
```
The equivalent configuration file for v2:  

```
{
    "emqxConfig": {
        "listeners": {
            "ssl": {
                "default": {
                   "bind": "8883",
                   "max_connections": "1024000",
                   "max_conn_rate": "500",
                   "ssl_options": {
                        "handshake_timeout": "15s"
                   }
                }
            }
        },
        "log": {
            "console": {
              "enable": true,
              "level": "warning"
            }
        }
    },
    "authMode": "enabled"
}
```
There is no equivalent to the `listener.ssl.external.rate_limit` configuration entry. The `use_greengrass_managed_certificates` configuration option has been removed.

**Example: Set a new port for the broker**  
The following example changes the port where the MQTT broker operates from the default 8883 to port 1234. If you are using Linux, include the `dockerOptions` field.  

```
{
  "emqxConfig": {
    "listeners": {
      "ssl": {
        "default": {
          "bind": 1234
        }
      }
    }
  },
  "dockerOptions": "-p 1234:1234"
}
```

**Example: Adjust the MQTT broker's log level**  
The following example changes the MQTT broker's log level to `debug`. You can choose from the following log levels:  
+ `debug`
+ `info`
+ `notice`
+ `warning`
+ `error`
+ `critical`
+ `alert`
+ `emergency`
The default log level is `warning`.  

```
{
  "emqxConfig": {
    "log": {
      "console": {
         "level": "debug"
      }
    }
  }
}
```

**Example: Enable the EMQX dashboard**  
The following example enables the EMQX dashboard so that you can monitor and manage your broker. If you are using Linux, include the `dockerOptions` field.   

```
{
  "emqxConfig": {
    "dashboard": {
      "listeners": {
        "http": {
          "bind": 18083
        }
      }
    }
  },
  "dockerOptions": "-p 18083:18083"
}
```

------
#### [ 1.0.0 - 1.2.2 ]

This component provides the following configuration parameters that you can customize when you deploy the component.

`emqx`  
(Optional) The [EMQX MQTT broker](https://www.emqx.io/docs/en/v4.4/configuration/configuration.html) configuration to use. You can configure a subset of EMQX configuration options in this component.  
This object contains the following information:    
`listener.ssl.external`  
(Optional) The port where the MQTT broker operates.  
<a name="mqtt-broker-configuration-mqtt-bridge-requirement"></a>If you specify a different port, and you use the [MQTT bridge component](mqtt-bridge-component.md) to relay MQTT messages to other brokers, you must use MQTT bridge v2.1.0 or later. Configure it to use the port where the MQTT broker operates.  
<a name="mqtt-broker-configuration-ip-detector-requirement"></a>If you specify a different port, and you use the [IP detector component](ip-detector-component.md) to manage MQTT broker endpoints, you must use IP detector v2.1.0 or later. Configure it to report the port where the MQTT broker operates.
Default: `8883`  
`listener.ssl.external.max_connections`  
(Optional) The maximum number of concurrent connections that the MQTT broker supports.  
Default: `1024000`  
`listener.ssl.external.max_conn_rate`  
(Optional) The maximum number of new connections per second the MQTT broker can receive.  
Default: `500`  
`listener.ssl.external.rate_limit`  
(Optional) The bandwidth limit for all connections to the MQTT broker. Specify the bandwidth and duration for that bandwidth separated by a comma (`,`) in the following format: `bandwidth,duration`. For example, you can specify `50KB,5s` to limit the MQTT broker to 50 kilobytes (KB) of data every 5 seconds.  
`listener.ssl.external.handshake_timeout`  
(Optional) The amount of time that the MQTT broker waits to finish authenticating a new connection.  
Default: `15s`  
`mqtt.max_packet_size`  
(Optional) The maximum size of an MQTT message.  
Default: `268435455` (256 MB minus 1)  
`log.level`  
(Optional) The log level for the MQTT broker. Choose from the following options:  
+ `debug`
+ `info`
+ `notice`
+ `warning`
+ `error`
+ `critical`
+ `alert`
+ `emergency`
The default log level is `warning`.

`requiresPrivilege`  
(Optional) On Linux core devices, you can specify to run the EMQX MQTT broker without root or administrator privileges. If you set this option to `false`, the system user that runs this component must be a member of the `docker` group.  
Default: `true`

`startupTimeoutSeconds`  
(Optional) The maximum of time in seconds for the EMQX MQTT broker to start. The component's state changes to `BROKEN` if it exceeds this timeout.  
Default: `90`

`ipcTimeoutSeconds`  
(Optional) The maximum of time in seconds for the component to wait for the Greengrass nucleus to respond to interprocess communication (IPC) requests. Increase this number if this component reports timeout errors when it checks if a client device is authorized.  
Default: `5`

`crtLogLevel`  
(Optional) The log level for the AWS Common Runtime (CRT) library.  
Defaults to the EMQX MQTT broker log level (`log.level` in `emqx`).

`restartIdentifier`  
(Optional) Configure this option to restart the EMQX MQTT broker. When this configuration value changes, this component restarts the MQTT broker. You can use this option to force client devices to disconnect.

`dockerOptions`  
(Optional) Configure this option only on Linux operating systems to add parameters to the Docker command line. For example, to map additional ports, use the `-p` Docker parameter:  

```
"-p 1883:1883"
```

`mergeConfigurationFiles`  
(Optional) Configure this option to add to or override the defaults in the specified EMQX configuration files. For information about the configuration files and their formats, see [Configuration](https://www.emqx.io/docs/en/v4.4/configuration/configuration.html) in the *EMQX 4.0 Documentation*. The values that you specify are appended to the configuration file.   
The following example updates the `etc/emqx.conf` file.  

```
"mergeConfigurationFiles": {
    "etc/emqx.conf": "broker.sys_interval=30s\nbroker.sys_heartbeat=10s"
},
```
In addition to the configuration files supported by EMQX, Greengrass supports a file that configures the Greengrass auth plugin for EMQX called `etc/plugins/aws_greengrass_emqx_auth.conf`. There are two supported options, `auth_mode` and `use_greengrass_managed_certificates`. To use another auth provider, set the `auth_mode` option to one of the following:  
+ `enabled` – (Default) Use the Greengrass authentication and authorization provider.
+ `bypass_on_failure` – Use the Greengrass authentication provider, then use any remaining authentication providers in the EMQX provider chain if Greengrass denies either authentication or authorization.
+ `bypass` – The Greengrass provider is disabled. Authentication and authorization is then handled by the EMQX provider chain.
If the `use_greengrass_managed_certificates` is `true`, this option indicates that Greengrass manages the broker TLS certificates. If `false`, it indicates that you provide the certificates through another source.  
The following example updates the defaults in the `etc/plugins/aws_greengrass_emqx_auth.conf` configuration file.  

```
"mergeConfigurationFiles": {
    "etc/plugins/aws_greengrass_emqx_auth.conf": "auth_mode=enabled\n use_greengrass_managed_certificates=true\n"
  },
```
`aws.greengrass.clientdevices.mqtt.EMQX` allows you to configure security-sensitive options. These include TLS settings, authentication, and authorization providers. The recommended configuration is the default configuration that uses mutual TLS authentication and the Greengrass Client Device Auth provider.

`replaceConfigurationFiles`  
(Optional) Configure this option to replace the specified EMQX configuration files. The values that you specify replace the entire existing configuration file. You can't specify the `etc/emqx.conf` file in this section. You must use `mergeConfigurationFile` to modify `etc/emqx.conf`.

**Example: Configuration merge update**  
The following example configuration specifies to operate the MQTT broker on port 443.  

```
{
  "emqx": {
    "listener.ssl.external": "443",
    "listener.ssl.external.max_connections": "1024000",
    "listener.ssl.external.max_conn_rate": "500",
    "listener.ssl.external.rate_limit": "50KB,5s",
    "listener.ssl.external.handshake_timeout": "15s",
    "log.level": "warning"
  },
  "requiresPrivilege": "true",
  "startupTimeoutSeconds": "90",
  "ipcTimeoutSeconds": "5"
}
```

------

## Local log file


This component uses the following log file.

------
#### [ Linux ]

```
/greengrass/v2/logs/aws.greengrass.clientdevices.mqtt.EMQX.log
```

------
#### [ Windows ]

```
C:\greengrass\v2\logs\aws.greengrass.clientdevices.mqtt.EMQX.log
```

------

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the path to the AWS IoT Greengrass root folder.

------
#### [ Linux ]

  ```
  sudo tail -f /greengrass/v2/logs/aws.greengrass.clientdevices.mqtt.EMQX.log
  ```

------
#### [ Windows (PowerShell) ]

  ```
  Get-Content C:\greengrass\v2\logs\aws.greengrass.clientdevices.mqtt.EMQX.log -Tail 10 -Wait
  ```

------

## Licenses


On Windows operating systems, this software includes code distributed under the [Microsoft Software License Terms - Microsoft Visual Studio Community 2022](https://visualstudio.microsoft.com/license-terms/vs2022-ga-community). By downloading this software, you agree to that code's license terms.

<a name="component-core-software-license"></a>This component is released under the [Greengrass Core Software License Agreement](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf).

## Changelog


The following table describes the changes in each version of the component.

------
#### [ v2.x ]


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.0.3  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/mqtt-broker-emqx-component.html)  | 
|  2.0.2  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/mqtt-broker-emqx-component.html)  | 
|  2.0.1  |  Version updated for [client device auth](client-device-auth-component.md) version 2.5.0 release.  | 
| 2.0.0 | This version of the MQTT 5 broker (EMQX) expects different configuration parameters than version 1.x. If you use a non-default configuration for version 1.x, you must update the component's configuration for 2.x. For more information, see [Configuration](#mqtt-broker-emqx-component-configuration). [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/mqtt-broker-emqx-component.html) | 

------
#### [ v1.x ]


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  1.2.3  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/mqtt-broker-emqx-component.html)  | 
|  1.2.2  |  Version updated for [client device auth](client-device-auth-component.md) version 2.4.0 release.  | 
|  1.2.1  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/mqtt-broker-emqx-component.html)  | 
|  1.2.0  |  Adds support for certificate chains.  | 
|  1.1.0  | <a name="changelog-emqx-1.1.0"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/mqtt-broker-emqx-component.html) | 
|  1.0.1  |  Fixes an issue during the TLS handshake which results in some MQTT clients failing to connect.  | 
|  1.0.0  |  Initial version.  | 

------

# Nucleus telemetry emitter
New nucleus telemetry emitter component[https://docs.aws.amazon.com/greengrass/v2/developerguide/nucleus-emitter-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/nucleus-emitter-component.html)

Version 1.0.10 of the nucleus telemetry emitter component is available.New nucleus telemetry emitter component[https://docs.aws.amazon.com/greengrass/v2/developerguide/nucleus-emitter-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/nucleus-emitter-component.html)

Version 1.0.9 of the nucleus telemetry emitter component is available.New nucleus telemetry emitter component[https://docs.aws.amazon.com/greengrass/v2/developerguide/nucleus-emitter-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/nucleus-emitter-component.html)

Version 1.0.0 of the nucleus telemetry emitter component is available. This AWS-provided component gathers system health telemetry data and publishes it continually to a local topic and an AWS IoT Core MQTT topic.

The nucleus telemetry emitter component (`aws.greengrass.telemetry.NucleusEmitter`) gathers system health telemetry data and publishes it continually to a local topic and an AWS IoT Core MQTT topic. This component enables you to gather real-time system telemetry on your Greengrass core devices. For information about the Greengrass telemetry agent that publishes system telemetry data to Amazon EventBridge, see [Gather system health telemetry data from AWS IoT Greengrass core devices](telemetry.md).

By default, the nucleus telemetry emitter component publishes telemetry data every 60 seconds to the following local publish/subscribe topic.

```
$local/greengrass/telemetry
```

The nucleus telemetry emitter component doesn't publish to an AWS IoT Core MQTT topic by default. You can configure this component to publish to an AWS IoT Core MQTT topic when you deploy it. The use of an MQTT topic to publish data to the AWS Cloud is subject to [AWS IoT Core pricing](https://aws.amazon.com/iot-core/pricing/).

<a name="greengrass-software-catalog-influxdb-telemetry-publisher"></a>AWS IoT Greengrass provides several [community components](greengrass-software-catalog.md) to help you analyze and visualize telemetry data locally on your core device using InfluxDB and Grafana. These components use telemetry data from the nucleus emitter component. For more information, see the README for the [InfluxDB publisher component](https://github.com/awslabs/aws-greengrass-labs-telemetry-influxdbpublisher).

**Topics**
+ [

## Versions
](#nucleus-emitter-component-versions)
+ [

## Type
](#nucleus-emitter-component-type)
+ [

## Operating system
](#nucleus-emitter-component-os-support)
+ [

## Dependencies
](#nucleus-emitter-component-dependencies)
+ [

## Configuration
](#nucleus-emitter-component-configuration)
+ [

## Output data
](#nucleus-emitter-component-output-data)
+ [

## Usage
](#nucleus-emitter-component-usage)
+ [

## Local log file
](#nucleus-emitter-component-log-file)
+ [

## Changelog
](#nucleus-emitter-component-changelog)

## Versions


This component has the following versions:
+ 1.0.x

## Type


<a name="public-component-type-plugin-para1"></a>This component is a plugin component (`aws.greengrass.plugin`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs this component in the same Java Virtual Machine (JVM) as the nucleus. The nucleus restarts when you change this component's version on the core device.

<a name="public-component-type-plugin-para2"></a>This component uses the same log file as the Greengrass nucleus. For more information, see [Monitor AWS IoT Greengrass logs](monitor-logs.md).

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on core devices that run the following operating systems:
+ Linux
+ Windows

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#nucleus-emitter-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

------
#### [ 1.0.12 ]

The following table lists the dependencies for version 1.0.12 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.4.0 <2.17.0 | Soft | 

------
#### [ 1.0.11 ]

The following table lists the dependencies for version 1.0.11 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.4.0 <2.16.0  | Hard | 

------
#### [ 1.0.10 ]

The following table lists the dependencies for version 1.0.10 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.4.0 <2.15.0  | Hard | 

------
#### [ 1.0.9 ]

The following table lists the dependencies for version 1.0.9 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.4.0 <2.14.0  | Hard | 

------
#### [ 1.0.8 ]

The following table lists the dependencies for version 1.0.8 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.4.0 <2.13.0  | Hard | 

------
#### [ 1.0.7 ]

The following table lists the dependencies for version 1.0.7 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.4.0 <2.12.0  | Hard | 

------
#### [ 1.0.6 ]

The following table lists the dependencies for version 1.0.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.4.0 <2.11.0  | Hard | 

------
#### [ 1.0.5 ]

The following table lists the dependencies for version 1.0.5 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.4.0 <2.10.0  | Hard | 

------
#### [ 1.0.4 ]

The following table lists the dependencies for version 1.0.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.4.0 <2.9.0  | Hard | 

------
#### [ 1.0.3 ]

The following table lists the dependencies for version 1.0.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.4.0 <2.8.0  | Hard | 

------
#### [ 1.0.2 ]

The following table lists the dependencies for version 1.0.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.4.0 <2.7.0  | Hard | 

------
#### [ 1.0.1 ]

The following table lists the dependencies for version 1.0.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.4.0 <2.6.0  | Hard | 

------
#### [ 1.0.0 ]

The following table lists the dependencies for version 1.0.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.4.0 <2.5.0  | Hard | 

------

For more information about component dependencies, see the [component recipe reference](component-recipe-reference.md#recipe-reference-component-dependencies).

## Configuration


This component provides the following configuration parameters that you can customize when you deploy the component.

`pubSubPublish`  
(Optional) Defines whether to publish telemetry data to the `$local/greengrass/telemetry` topic. Supported values are `true` and `false`.  
Default: `true`

`mqttTopic`  
(Optional) The AWS IoT Core MQTT topic to which this component publishes telemetry data.  
Set this value to the AWS IoT Core MQTT topic to which you want to publish telemetry data. When this value is empty, the nucleus emitter doesn't publish telemetry data to the AWS Cloud.   
The use of an MQTT topic to publish data to the AWS Cloud is subject to [AWS IoT Core pricing](https://aws.amazon.com/iot-core/pricing/).
Default: `""`

`telemetryPublishIntervalMs`  
(Optional) The amount of time (in milliseconds) between which the component publishes telemetry data. If you set this value lower than the minimum supported value, the component uses the minimum value instead.  
Lower publish intervals result in higher CPU usage on your core device. We recommend that you start with the default publish interval and adjust it based on your device's CPU usage.
Minimum: `500`  
Default: `60000`

**Example: Configuration merge update**  
The following example shows a sample configuration merge update that enables publishing telemetry data every 5 seconds to the `$local/greengrass/telemetry` topic and the `greengrass/myTelemetry` AWS IoT Core MQTT topic.  

```
{
  "pubSubPublish": "true",
  "mqttTopic": "greengrass/myTelemetry",
  "telemetryPublishIntervalMs": 5000
}
```

## Output data


This component publishes telemetry metrics as a JSON array on the following topic. 

**Local topic:** `$local/greengrass/telemetry`

You can optionally choose to also publish telemetry metrics to an AWS IoT Core MQTT topic. For more information about topics, see [MQTT topics](https://docs.aws.amazon.com/iot/latest/developerguide/topics.html) in the *AWS IoT Core Developer Guide*.

**Example data**  

```
[
  {
    "A": "Average",
    "N": "CpuUsage",
    "NS": "SystemMetrics",
    "TS": 1627597331445,
    "U": "Percent",
    "V": 26.21981271562346
  },
  {
    "A": "Count",
    "N": "TotalNumberOfFDs",
    "NS": "SystemMetrics",
    "TS": 1627597331445,
    "U": "Count",
    "V": 7316
  },
  {
    "A": "Count",
    "N": "SystemMemUsage",
    "NS": "SystemMetrics",
    "TS": 1627597331445,
    "U": "Megabytes",
    "V": 10098
  },
  {
    "A": "Count",
    "N": "NumberOfComponentsStarting",
    "NS": "GreengrassComponents",
    "TS": 1627597331446,
    "U": "Count",
    "V": 0
  },
  {
    "A": "Count",
    "N": "NumberOfComponentsInstalled",
    "NS": "GreengrassComponents",
    "TS": 1627597331446,
    "U": "Count",
    "V": 0
  },
  {
    "A": "Count",
    "N": "NumberOfComponentsStateless",
    "NS": "GreengrassComponents",
    "TS": 1627597331446,
    "U": "Count",
    "V": 0
  },
  {
    "A": "Count",
    "N": "NumberOfComponentsStopping",
    "NS": "GreengrassComponents",
    "TS": 1627597331446,
    "U": "Count",
    "V": 0
  },
  {
    "A": "Count",
    "N": "NumberOfComponentsBroken",
    "NS": "GreengrassComponents",
    "TS": 1627597331446,
    "U": "Count",
    "V": 0
  },
  {
    "A": "Count",
    "N": "NumberOfComponentsRunning",
    "NS": "GreengrassComponents",
    "TS": 1627597331446,
    "U": "Count",
    "V": 7
  },
  {
    "A": "Count",
    "N": "NumberOfComponentsErrored",
    "NS": "GreengrassComponents",
    "TS": 1627597331446,
    "U": "Count",
    "V": 0
  },
  {
    "A": "Count",
    "N": "NumberOfComponentsNew",
    "NS": "GreengrassComponents",
    "TS": 1627597331446,
    "U": "Count",
    "V": 0
  },
  {
    "A": "Count",
    "N": "NumberOfComponentsFinished",
    "NS": "GreengrassComponents",
    "TS": 1627597331446,
    "U": "Count",
    "V": 2
  }
]
```<a name="telemetry-json-array-config"></a>

The output array contains a list of metrics that have the following properties:

`A`  
The aggregation type for the metric.   
For the `CpuUsage` metric, this property is set to `Average` because the published value of the metric is the average CPU usage amount since the last publish event.  
For all other metrics, the nucleus emitter doesn't aggregate the metric value, and this property is set to `Count`.

`N`  
The name of the metric.

`NS`  
The metric namespace.

`TS`  
The timestamp of when the data was gathered.

`U`  
The unit of the metric value.

`V`  
The metric value. 

The nucleus emitter publishes the following metrics:


| Name | Description | 
| --- | --- | 
|  **System**  | 
|  `SystemMemUsage`  |  The amount of memory currently in use by all applications on the Greengrass core device, including the operating system.  | 
|  `CpuUsage`  |  The amount of CPU currently in use by all applications on the Greengrass core device, including the operating system.  | 
|  `TotalNumberOfFDs`  |  The number of file descriptors stored by the operating system of the Greengrass core device. One file descriptor uniquely identifies one open file.  | 
|  **Greengrass nucleus**  | 
|  `NumberOfComponentsRunning`  |  The number of components that are running on the Greengrass core device.  | 
|  `NumberOfComponentsErrored`  |  The number of components that are in error state on the Greengrass core device.  | 
|  `NumberOfComponentsInstalled`  |  The number of components that are installed on the Greengrass core device.  | 
|  `NumberOfComponentsStarting`  |  The number of components that are starting on the Greengrass core device.  | 
|  `NumberOfComponentsNew`  |  The number of components that are new on the Greengrass core device.  | 
|  `NumberOfComponentsStopping`  |  The number of components that are stopping on the Greengrass core device.  | 
|  `NumberOfComponentsFinished`  |  The number of components that are finished on the Greengrass core device.  | 
|  `NumberOfComponentsBroken`  |  The number of components that are broken on the Greengrass core device.  | 
|  `NumberOfComponentsStateless`  |  The number of components that are stateless on the Greengrass core device.  | 

## Usage


To use system health telemetry data, you can create custom components that subscribe to the topics to which the nucleus emitter publishes the telemetry data, and react to that data as needed. Because the nucleus emitter component provides the option to publish telemetry data to a local topic, you can subscribe to that topic, and use the published data to act locally on your core device. The core device can then react to telemetry data even when it has limited connectivity to the cloud.

For example, you can configure a component that listens on the `$local/greengrass/telemetry` topic for telemetry data and send the data to the stream manager component to stream your data to the AWS Cloud. For more information about creating such a component, see [Publish/subscribe local messages](ipc-publish-subscribe.md) and [Create custom components that use stream manager](use-stream-manager-in-custom-components.md).

## Local log file


This component uses the same log file as the [Greengrass nucleus](greengrass-nucleus-component.md) component.

------
#### [ Linux ]

```
/greengrass/v2/logs/greengrass.log
```

------
#### [ Windows ]

```
C:\greengrass\v2\logs\greengrass.log
```

------

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the path to the AWS IoT Greengrass root folder.

------
#### [ Linux ]

  ```
  sudo tail -f /greengrass/v2/logs/greengrass.log
  ```

------
#### [ Windows (PowerShell) ]

  ```
  Get-Content C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
  ```

------

## Changelog


The following table describes the changes in each version of the component.


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  1.0.12  |  Version updated for Greengrass nucleus version 2.16.0 release.  | 
|  1.0.11  | Version updated for Greengrass nucleus version 2.15.0 release. | 
|  1.0.10  | Version updated for Greengrass nucleus version 2.14.0 release. | 
|  1.0.9  | Version updated for Greengrass nucleus version 2.13.0 release. | 
|  1.0.8  | Version updated for Greengrass nucleus version 2.12.0 release. | 
|  1.0.7  | Version updated for Greengrass nucleus version 2.11.0 release. | 
|  1.0.6  | Version updated for Greengrass nucleus version 2.10.0 release. | 
|  1.0.5  | Version updated for Greengrass nucleus version 2.9.0 release. | 
|  1.0.4  | Version updated for Greengrass nucleus version 2.8.0 release. | 
|  1.0.3  |  Version updated for Greengrass nucleus version 2.7.0 release.  | 
|  1.0.2  |  Version updated for Greengrass nucleus version 2.6.0 release.  | 
|  1.0.1  |  Version updated for Greengrass nucleus version 2.5.0 release.  | 
|  1.0.0  |  Initial version.  | 

# PKCS\$111 provider


The PKCS\$111 provider component (`aws.greengrass.crypto.Pkcs11Provider`) enables you to 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 component enables you to securely store certificate and private key files so that they aren't exposed or duplicated in software. For more information, see [Hardware security integration](hardware-security.md).

To provision a Greengrass core device that stores its certificate and private key in an HSM, you must specify this component as a provisioning plugin when you install the AWS IoT Greengrass Core software. For more information, see [Install AWS IoT Greengrass Core software with manual resource provisioning](manual-installation.md).

AWS 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).

**Topics**
+ [

## Versions
](#pkcs11-provider-component-versions)
+ [

## Type
](#pkcs11-provider-component-type)
+ [

## Operating system
](#pkcs11-provider-component-os-support)
+ [

## Requirements
](#pkcs11-provider-component-requirements)
+ [

## Dependencies
](#pkcs11-provider-component-dependencies)
+ [

## Configuration
](#pkcs11-provider-component-configuration)
+ [

## Local log file
](#pkcs11-provider-component-log-file)
+ [

## Changelog
](#pkcs11-provider-component-changelog)

## Versions


This component has the following versions:
+ 2.0.x

## Type


<a name="public-component-type-plugin-para1"></a>This component is a plugin component (`aws.greengrass.plugin`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs this component in the same Java Virtual Machine (JVM) as the nucleus. The nucleus restarts when you change this component's version on the core device.

<a name="public-component-type-plugin-para2"></a>This component uses the same log file as the Greengrass nucleus. For more information, see [Monitor AWS IoT Greengrass logs](monitor-logs.md).

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on Linux core devices only.

## Requirements


This component has the following requirements:
+ <a name="hardware-security-module-requirements-key"></a>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**  <a name="hardware-security-module-requirements-key-notes"></a>
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 name="hardware-security-module-requirements-pkcs11-provider-library"></a>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`
+ <a name="hardware-security-module-requirements-slot-label"></a>The hardware module must be resolvable by slot label, as defined in the PKCS\$111 specification.
+ <a name="hardware-security-module-requirements-private-key-and-certificate"></a>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.
+ <a name="hardware-security-module-requirements-object-label"></a>The certificate and private key must be resolvable by object labels.
+ <a name="hardware-security-module-requirements-private-key-permissions"></a>The private key must have the following permissions:
  + `sign`
  + `decrypt`
+ <a name="hardware-security-module-requirements-secret-manager-permissions"></a>(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`
+ <a name="hardware-security-module-requirements-environment-variable"></a>(Optional) If you are using the TPM2 library and running the Greengrass core as a service, you must provide an environment variable with the location of the PKCS\$111 store. The following example is a systemd service file with the required environment variable:

  ```
  [Unit]
  Description=Greengrass Core
  After=network.target
  
  [Service]
  Type=simple
  PIDFile=/var/run/greengrass.pid
  Environment=TPM2_PKCS11_STORE=/path/to/store/directory
  RemainAfterExit=no
  Restart=on-failure
  RestartSec=10
  ExecStart=/bin/sh /greengrass/v2/alts/current/distro/bin/loader
  
  [Install]
  WantedBy=multi-user.target
  ```

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#pkcs11-provider-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

------
#### [ 2.0.11 ]

The following table lists the dependencies for version 2.0.11 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.3 <2.17.0 | Soft | 

------
#### [ 2.0.10 ]

The following table lists the dependencies for version 2.0.10 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.3 <2.16.0  | Soft | 

------
#### [ 2.0.9 ]

The following table lists the dependencies for version 2.0.9 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.3 <2.15.0  | Soft | 

------
#### [ 2.0.8 ]

The following table lists the dependencies for version 2.0.8 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.3 <2.14.0  | Soft | 

------
#### [ 2.0.7 ]

The following table lists the dependencies for version 2.0.7 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.3 <2.13.0  | Soft | 

------
#### [ 2.0.6 ]

The following table lists the dependencies for version 2.0.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.3 <2.12.0  | Soft | 

------
#### [ 2.0.5 ]

The following table lists the dependencies for version 2.0.5 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.3 <2.11.0  | Soft | 

------
#### [ 2.0.4 ]

The following table lists the dependencies for version 2.0.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.3 <2.10.0  | Soft | 

------
#### [ 2.0.3 ]

The following table lists the dependencies for version 2.0.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.3 <2.9.0  | Soft | 

------
#### [ 2.0.2 ]

The following table lists the dependencies for version 2.0.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.3 <2.8.0  | Soft | 

------
#### [ 2.0.1 ]

The following table lists the dependencies for version 2.0.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.5.3 <2.7.0  | Soft | 

------
#### [ 2.0.0 ]

The following table lists the dependencies for version 2.0.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.5.3 <2.6.0  | Soft | 

------

For more information about component dependencies, see the [component recipe reference](component-recipe-reference.md#recipe-reference-component-dependencies).

## Configuration


This component provides the following configuration parameters that you can customize when you deploy the component.<a name="pkcs11-provider-component-configuration-parameters"></a>

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

**Example: Configuration merge update**  

```
{
  "name": "softhsm_pkcs11",
  "library": "/usr/lib/softhsm/libsofthsm2.so",
  "slot": 1,
  "userPin": "1234"
}
```

## Local log file


This component uses the same log file as the [Greengrass nucleus](greengrass-nucleus-component.md) component.

------
#### [ Linux ]

```
/greengrass/v2/logs/greengrass.log
```

------
#### [ Windows ]

```
C:\greengrass\v2\logs\greengrass.log
```

------

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the path to the AWS IoT Greengrass root folder.

------
#### [ Linux ]

  ```
  sudo tail -f /greengrass/v2/logs/greengrass.log
  ```

------
#### [ Windows (PowerShell) ]

  ```
  Get-Content C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
  ```

------

## Changelog


The following table describes the changes in each version of the component.


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.0.11  |  Version updated for Greengrass nucleus version 2.16.0 release.  | 
|  2.0.10  | Version updated for Greengrass nucleus version 2.15.0 release. | 
|  2.0.9  | Version updated for Greengrass nucleus version 2.14.0 release. | 
|  2.0.8  | Version updated for Greengrass nucleus version 2.13.0 release. | 
|  2.0.7  | Version updated for Greengrass nucleus version 2.12.0 release. | 
|  2.0.6  | Version updated for Greengrass nucleus version 2.11.0 release. | 
|  2.0.5  | Version updated for Greengrass nucleus version 2.10.0 release. | 
|  2.0.4  | Version updated for Greengrass nucleus version 2.9.0 release. | 
|  2.0.3  | Version updated for Greengrass nucleus version 2.8.0 release. | 
|  2.0.2  |  Version updated for Greengrass nucleus version 2.7.0 release.  | 
|  2.0.1  |  Version updated for Greengrass nucleus version 2.6.0 release.  | 
|  2.0.0  |  Initial version.  | 

# Secret manager
Secret manager v2.2.5 released[https://docs.aws.amazon.com//greengrass/v2/developerguide/secret-manager-component.html](https://docs.aws.amazon.com//greengrass/v2/developerguide/secret-manager-component.html)

Secret manager v2.2.5 is available. This version fixes an issue where a secret doesn't get fetched from the AWS Cloud if it isn't present in the local cache.Secret manager v2.2.4 released[https://docs.aws.amazon.com//greengrass/v2/developerguide/secret-manager-component.html](https://docs.aws.amazon.com//greengrass/v2/developerguide/secret-manager-component.html)

Secret manager v2.2.4 is available. This version reduces the frequency of writes to the local secret store. Secret manager now writes to the local store only when secrets are updated.Secret manager v2.2.3 released[https://docs.aws.amazon.com//greengrass/v2/developerguide/secret-manager-component.html](https://docs.aws.amazon.com//greengrass/v2/developerguide/secret-manager-component.html)

Secret manager v2.2.3 is available. This version fixes an issue where secret manager wipes the locally persisted secrets when the core device is offline and the device’s security service (such as an HSM) is unavailable.

The secret manager component (`aws.greengrass.SecretManager`) deploys secrets from AWS Secrets Manager to Greengrass core devices. Use this component to securely use credentials, such as passwords, in custom components on your Greengrass core devices. For more information about Secrets Manager, see [What is AWS Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) in the *AWS Secrets Manager User Guide*.

To access this component's secrets in your custom Greengrass components, use the [GetSecretValue](ipc-secret-manager.md#ipc-operation-getsecretvalue) operation in the AWS IoT Device SDK. For more information, see [Use the AWS IoT Device SDK to communicate with the Greengrass nucleus, other components, and AWS IoT CoreCommunicate with the Greengrass nucleus, other components, and AWS IoT Core](interprocess-communication.md) and [Retrieve secret values](ipc-secret-manager.md).

This component encrypts secrets on the core device to keep your credentials and passwords secure until you need to use them. It uses the core device's private key to encrypt and decrypt secrets.

**Topics**
+ [

## Versions
](#secret-manager-component-versions)
+ [

## Type
](#secret-manager-component-type)
+ [

## Operating system
](#secret-manager-component-os-support)
+ [

## Requirements
](#secret-manager-component-requirements)
+ [

## Dependencies
](#secret-manager-component-dependencies)
+ [

## Configuration
](#secret-manager-component-configuration)
+ [

## Local log file
](#secret-manager-component-log-file)
+ [

## Changelog
](#secret-manager-component-changelog)

## Versions


This component has the following versions:
+ 2.2.x
+ 2.1.x
+ 2.0.x

## Type


<a name="public-component-type-plugin-para1"></a>This component is a plugin component (`aws.greengrass.plugin`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs this component in the same Java Virtual Machine (JVM) as the nucleus. The nucleus restarts when you change this component's version on the core device.

<a name="public-component-type-plugin-para2"></a>This component uses the same log file as the Greengrass nucleus. For more information, see [Monitor AWS IoT Greengrass logs](monitor-logs.md).

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on core devices that run the following operating systems:
+ Linux
+ Windows

## Requirements


This component has the following requirements:
+ The [Greengrass device role](device-service-role.md) must allow the `secretsmanager:GetSecretValue` action, as shown in the following example IAM policy.

------
#### [ JSON ]

****  

  ```
  {
    "Version":"2012-10-17",		 	 	 
    "Statement": [
      {
        "Action": [
          "secretsmanager:GetSecretValue"
        ],
        "Effect": "Allow",
        "Resource": [
        "arn:aws:secretsmanager:us-east-1:123456789012:secret:MySecret"
        ]
      }
    ]
  }
  ```

------

  ```
  ```
**Note**  
If you use a customer-managed AWS Key Management Service key to encrypt secrets, the device role must also allow the `kms:Decrypt` action.

  For more information about IAM policies for Secrets Manager, see the following in the *AWS Secrets Manager User Guide*:
  + [Authentication and access control for AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access.html)
  + [Actions, resources, and context keys you can use in an IAM policy or secret policy for AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/reference_iam-permissions.html)
+ Custom components must define an authorization policy that allows `aws.greengrass#GetSecretValue` to get secrets that you store with this component. In this authorization policy, you can restrict components' access to specific secrets. For more information, see [secret manager IPC authorization](ipc-secret-manager.md#ipc-secret-manager-authorization).
+ (Optional) If you store the core device's private key and certificate in a [hardware security module](hardware-security.md) (HSM), the HSM must support RSA keys, the private key must have the `unwrap` permission, and the public key must have the `wrap` permission.

### Endpoints and ports


This component must be able to perform outbound requests to the following endpoints and ports, in addition to endpoints and ports required for basic operation. For more information, see [Allow device traffic through a proxy or firewall](allow-device-traffic.md).


| Endpoint | Port | Required | Description | 
| --- | --- | --- | --- | 
|  `secretsmanager.region.amazonaws.com`  | 443 | Yes |  Download secrets to the core device.  | 

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#secret-manager-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

------
#### [ 2.2.7 ]

The following table lists the dependencies for version 2.2.7 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.0 <2.17.0 | Soft | 

------
#### [ 2.2.6 ]

The following table lists the dependencies for version 2.2.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.0 <2.16.0 | Soft | 

------
#### [ 2.2.2 – 2.2.5 ]

The following table lists the dependencies for versions 2.2.2 through 2.2.5 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.0 <2.15.0 | Soft | 

------
#### [ 2.2.0 ]

The following table lists the dependencies for versions 2.2.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.13.0 <2.14.0 | Soft | 

------
#### [ 2.1.7 – 2.1.8 ]

The following table lists the dependencies for versions 2.1.7 and 2.1.8 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.0 <2.13.0 | Soft | 

------
#### [ 2.1.6 ]

The following table lists the dependencies for version 2.1.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.0 <2.12.0 | Soft | 

------
#### [ 2.1.5 ]

The following table lists the dependencies for version 2.1.5 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.0 <2.11.0 | Soft | 

------
#### [ 2.1.4 ]

The following table lists the dependencies for version 2.1.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.0 <2.10.0 | Soft | 

------
#### [ 2.1.3 ]

The following table lists the dependencies for version 2.1.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.0 <2.9.0 | Soft | 

------
#### [ 2.1.2 ]

The following table lists the dependencies for version 2.1.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.0 <2.8.0 | Soft | 

------
#### [ 2.1.1 ]

The following table lists the dependencies for version 2.1.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.0 <2.7.0 | Soft | 

------
#### [ 2.1.0 ]

The following table lists the dependencies for version 2.1.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.0 <2.6.0 | Soft | 

------
#### [ 2.0.9 ]

The following table lists the dependencies for version 2.0.9 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.5.0  | Soft | 

------
#### [ 2.0.8 ]

The following table lists the dependencies for version 2.0.8 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.4.0  | Soft | 

------
#### [ 2.0.7 ]

The following table lists the dependencies for version 2.0.7 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.3.0  | Soft | 

------
#### [ 2.0.6 ]

The following table lists the dependencies for version 2.0.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.2.0  | Soft | 

------
#### [ 2.0.4 and 2.0.5 ]

The following table lists the dependencies for versions 2.0.4 and 2.0.5 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.3 <2.1.0  | Soft | 

------

For more information about component dependencies, see the [component recipe reference](component-recipe-reference.md#recipe-reference-component-dependencies).

## Configuration


This component provides the following configuration parameters that you can customize when you deploy the component.

`periodicRefreshIntervalMin` (optional)  
The interval in minutes where this component syncs the configured secrets on the core device with the latest secret values from the AWS Secrets Manager service. If this interval is not configured, secret manager will not refresh the configured secrets periodically.  

```
{
  "cloudSecrets": [
    {
      "arn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:MyGreengrassSecret-abcdef"
    }
  ],
  "periodicRefreshIntervalMin" : 60
}
```

`cloudSecrets`  
A list of Secrets Manager secrets to deploy to the core device. You can specify labels to define which versions of each secret to deploy. If you don't specify a version, this component deploys the version with the staging label `AWSCURRENT` attached. For more information, see [Staging labels](https://docs.aws.amazon.com/secretsmanager/latest/userguide/terms-concepts.html#term_staging-label) in the *AWS Secrets Manager User Guide*.  
The secret manager component caches secrets locally. If the secret value changes in Secrets Manager, this component doesn't automatically retrieve the new value. To update the local copy, give the secret a new label and configure this component to retrieve the secret identified by the new label.  
Each object contains the following information:    
`arn`  
The ARN of the secret to deploy. The ARN of the secret can either be a full ARN or a partial ARN. We recommend that you specify a complete ARN rather than a partial ARN. For more information, see [Finding a secret from a partial ARN](https://docs.aws.amazon.com/secretsmanager/latest/userguide/troubleshoot.html#ARN_secretnamehyphen). The following is an example of a full ARN and a partial ARN:  
+ Full ARN: `arn:aws:secretsmanager:us-east-2:111122223333:secret:SecretName-abcdef`
+ Partial ARN: `arn:aws:secretsmanager:us-east-2:111122223333:secret:SecretName`  
`labels`  
(Optional) A list of labels to identify the versions of the secret to deploy to the core device.  
Each label must be a string.

**Example: Configuration merge update**  

```
{
  "cloudSecrets": [
    {
      "arn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:MyGreengrassSecret-abcdef"
    }
  ]
}
```

## Local log file


This component uses the same log file as the [Greengrass nucleus](greengrass-nucleus-component.md) component.

------
#### [ Linux ]

```
/greengrass/v2/logs/greengrass.log
```

------
#### [ Windows ]

```
C:\greengrass\v2\logs\greengrass.log
```

------

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the path to the AWS IoT Greengrass root folder.

------
#### [ Linux ]

  ```
  sudo tail -f /greengrass/v2/logs/greengrass.log
  ```

------
#### [ Windows (PowerShell) ]

  ```
  Get-Content C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
  ```

------

## Changelog


The following table describes the changes in each version of the component.


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.2.7  |  Version updated for Greengrass nucleus version 2.16.0 release.  | 
|  2.2.6  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/secret-manager-component.html)  | 
|  2.2.5  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/secret-manager-component.html)  | 
|  2.2.4  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/secret-manager-component.html)  | 
|  2.2.3  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/secret-manager-component.html)  | 
|  2.2.2  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/secret-manager-component.html)  | 
|  2.2.1  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/secret-manager-component.html)  | 
|  2.2.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/secret-manager-component.html)  | 
|  2.1.8  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/secret-manager-component.html)  | 
|  2.1.7  | Version updated for Greengrass nucleus version 2.12.0 release. | 
|  2.1.6  | Version updated for Greengrass nucleus version 2.11.0 release. | 
|  2.1.5  | Version updated for Greengrass nucleus version 2.10.0 release. | 
|  2.1.4  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/secret-manager-component.html)  | 
|  2.1.3  | Version updated for Greengrass nucleus version 2.8.0 release. | 
|  2.1.2  |  Version updated for Greengrass nucleus version 2.7.0 release.  | 
|  2.1.1  |  Version updated for Greengrass nucleus version 2.6.0 release.  | 
|  2.1.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/secret-manager-component.html)  | 
|  2.0.9  |  Version updated for Greengrass nucleus version 2.4.0 release.  | 
|  2.0.8  |  Version updated for Greengrass nucleus version 2.3.0 release.  | 
|  2.0.7  |  Version updated for Greengrass nucleus version 2.2.0 release.  | 
|  2.0.6  |  Version updated for Greengrass nucleus version 2.1.0 release.  | 
|  2.0.5  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/secret-manager-component.html)  | 
|  2.0.4  |  Initial version.  | 

# Secure tunneling
Secure tunneling v1.1.3 released[https://docs.aws.amazon.com//greengrass/v2/developerguide/secure-tunneling-component.html](https://docs.aws.amazon.com//greengrass/v2/developerguide/secure-tunneling-component.html)

Secure tunneling v1.1.3 is available. This version upgrades the underlying AWS IoT Device Client invoked by the component from version 1.10.0 to version 1.10.1. This version also fixes the GNU C Library (glibc) compatibility issues in secure tunneling component version 1.1.2.Secure tunneling v1.1.2 released[https://docs.aws.amazon.com//greengrass/v2/developerguide/secure-tunneling-component.html](https://docs.aws.amazon.com//greengrass/v2/developerguide/secure-tunneling-component.html)

Secure tunneling v1.1.2 is available. This version upgrades the underlying AWS IoT Device Client invoked by the component from version 1.9.0 to version 1.10.0. Secure tunneling v1.1.2 also fixes the payload transfer issue which prevents users from forwarding large files from Greengrass V2 core devices to the source device through the secure tunnel.Secure tunneling v1.1.1 released[https://docs.aws.amazon.com//greengrass/v2/developerguide/secure-tunneling-component.html](https://docs.aws.amazon.com//greengrass/v2/developerguide/secure-tunneling-component.html)

Secure tunneling v1.1.1 is available. This version adds configuration to support Greengrass nucleus lite.Secure tunneling v1.1.0 released[https://docs.aws.amazon.com//greengrass/v2/developerguide/secure-tunneling-component.html](https://docs.aws.amazon.com//greengrass/v2/developerguide/secure-tunneling-component.html)

Secure tunneling v1.1.0 is available. This version adds recipe supports for Greengrass nucleus lite.Secure tunneling v1.0.19 released[https://docs.aws.amazon.com//greengrass/v2/developerguide/secure-tunneling-component.html](https://docs.aws.amazon.com//greengrass/v2/developerguide/secure-tunneling-component.html)

Secure tunneling v1.0.19 is available. This version upgrades the underlying AWS IoT Device Client invoked by the component from version 1.8.0 to version 1.9.0. Secure tunneling v1.0.19 increases the concurrent tunnel limit to 20 tunnels on a component level. This new version also increases AWS IoT Greengrass Core IPC timeout from 3 seconds to 10 seconds.Secure tunneling v1.0.17 released[https://docs.aws.amazon.com//greengrass/v2/developerguide/secure-tunneling-component.html](https://docs.aws.amazon.com//greengrass/v2/developerguide/secure-tunneling-component.html)

Secure tunneling v1.0.17 is available.New secure tunneling component released[https://docs.aws.amazon.com//greengrass/v2/developerguide/secure-tunneling-component.html](https://docs.aws.amazon.com//greengrass/v2/developerguide/secure-tunneling-component.html)

Version 1.0.0 of the secure tunneling component is available for AWS IoT Greengrass. This AWS-provided component uses AWS IoT secure tunneling to establish secure bidirectional communication with a Greengrass core device that is behind restricted firewalls.

With the `aws.greengrass.SecureTunneling` component, you can establish secure bidirectional communication with a Greengrass core device located behind restricted firewalls.

For example, imagine you have a Greengrass core device behind a firewall that prohibits all incoming connections. Secure tunneling uses MQTT to transfer an access token to the device and then uses WebSockets to make an SSH connection to the device through the firewall. With this AWS IoT managed tunnel, you can open the SSH connection needed for your device. For more information about using AWS IoT secure tunneling to connect to remote devices, see [AWS IoT secure tunneling](https://docs.aws.amazon.com/iot/latest/developerguide/secure-tunneling.html) in the *AWS IoT Developer Guide*.

This component subscribes to the AWS IoT Core MQTT message broker on the `$aws/things/greengrass-core-device/tunnels/notify` topic to receive secure tunneling notifications.

**Topics**
+ [

## Versions
](#secure-tunneling-component-versions)
+ [

## Type
](#secure-tunneling-component-type)
+ [

## Operating system
](#secure-tunneling-component-os-support)
+ [

## Requirements
](#secure-tunneling-component-requirements)
+ [

## Dependencies
](#secure-tunneling-component-dependencies)
+ [

## Configuration
](#secure-tunneling-component-configuration)
+ [

## Local log file
](#secure-tunneling-component-log-file)
+ [

## Licenses
](#secure-tunneling-component-licenses)
+ [

## Usage
](#secure-tunneling-component-usage)
+ [

## See also
](#secure-tunneling-component-see-also)
+ [

## Changelog
](#secure-tunneling-component-changelog)

## Versions


This component has the following versions:
+ 1.1.x
+ 1.0.x

## Type


<a name="public-component-type-generic"></a>This <a name="public-component-type-generic-phrase"></a>component is a generic component (`aws.greengrass.generic`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs the component's lifecycle scripts.

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on Linux core devices only.

Architectures:
+ Armv71
+ Armv8 (AArch64)
+ x86\$164

## Requirements


This component has the following requirements:
+ Minimum of 32 MB disk space available for the secure tunneling component. This requirement does not include the Greengrass core software or other components running on the same device.
+ Minimum of 16 MB RAM available for the secure tunneling component. This requirement does not include the Greengrass core software or other components running on the same device. For more information, see [Control memory allocation with JVM options](configure-greengrass-core-v2.md#jvm-tuning).
+ GNU C Library (glibc) version 2.25 or greater with a Linux kernel of 3.2 or greater are required for the secure tunneling component version 1.0.12 and greater. Versions of the operating system and libraries past their long-term support end of life date are not supported. You should use an operating system and libraries with long-term support.
+ Both the operating system and the Java runtime must be installed as 64 bit.
+ [Python](https://www.python.org/) 3.5 or later installed on the Greengrass core device and added to the PATH environment variable.
+ `libcrypto.so.1.1` installed on the Greengrass core device and added to the PATH environment variable.
+ Open outbound traffic on port 443 on the Greengrass core device.
+ Turn on support for the communication service that you want to use to communicate with the Greengrass core device. For example, to open an SSH connection to the device, you must turn on SSH on that device.

### Endpoints and ports


This component must be able to perform outbound requests to the following endpoints and ports, in addition to endpoints and ports required for basic operation. For more information, see [Allow device traffic through a proxy or firewall](allow-device-traffic.md).


| Endpoint | Port | Required | Description | 
| --- | --- | --- | --- | 
|  `data.tunneling.iot.region.amazonaws.com`  | 443 | Yes |  Establish secure tunnels.  | 

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#secure-tunneling-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

------
#### [ 1.0.19 – 1.1.3 ]

The following table lists the dependencies for versions 1.0.19 through 1.1.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <3.0.0  | Soft | 

------
#### [ 1.0.18 ]

The following table lists the dependencies for version 1.0.18 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.13.0  | Soft | 

------
#### [ 1.0.16 – 1.0.17 ]

The following table lists the dependencies for versions 1.0.16 to 1.0.17 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.12.0  | Soft | 

------
#### [ 1.0.14 – 1.0.15 ]

The following table lists the dependencies for versions 1.0.14 to 1.0.15 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.11.0  | Soft | 

------
#### [ 1.0.11 – 1.0.13 ]

The following table lists the dependencies for versions 1.0.11 – 1.0.13 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.10.0  | Soft | 

------
#### [ 1.0.10 ]

The following table lists the dependencies for version 1.0.10 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.9.0  | Soft | 

------
#### [ 1.0.9 ]

The following table lists the dependencies for version 1.0.9 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.8.0  | Soft | 

------
#### [ 1.0.8 ]

The following table lists the dependencies for version 1.0.8 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.7.0  | Soft | 

------
#### [ 1.0.5 - 1.0.7 ]

The following table lists the dependencies for versions 1.0.5 through 1.0.7 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.6.0  | Soft | 

------
#### [ 1.0.4 ]

The following table lists the dependencies for version 1.0.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.5.0  | Soft | 

------
#### [ 1.0.3 ]

The following table lists the dependencies for version 1.0.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.4.0  | Soft | 

------
#### [ 1.0.2 ]

The following table lists the dependencies for version 1.0.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.3.0  | Soft | 

------
#### [ 1.0.1 ]

The following table lists the dependencies for version 1.0.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.2.0  | Soft | 

------
#### [ 1.0.0 ]

The following table lists the dependencies for version 1.0.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.3 <2.1.0  | Soft | 

------

For more information about component dependencies, see the [component recipe reference](component-recipe-reference.md#recipe-reference-component-dependencies).

## Configuration


This component provides the following configuration parameters that you can customize when you deploy the component.

`OS_DIST_INFO`  
(Optional) The operating system of your core device. By default, the component attempts to identify automatically the operating system running on your core device. If the component fails to start with the default value, use this value to specify the operating system. For a list of supported operating systems for this component, see [Device requirements](greengrass-nucleus-component.md#greengrass-v2-requirements).  
This value can be one of the following: `auto`, `ubuntu`, `amzn2`, `raspberrypi`.  
Default: `auto`

`accessControl`  
(Optional) The object that contains the [authorization policy](interprocess-communication.md#ipc-authorization-policies) that allows the component to subscribe to the secure tunneling notifications topic.   
Do not modify this configuration parameter if your deployment targets a thing group. If your deployment targets an individual core device, and you want to restrict its subscription to the device's topic, specify the core device's thing name. In the `resources` value in the device's authorization policy, replace the MQTT topic wildcard with the device's thing name. 

```
{
  "aws.greengrass.ipc.mqttproxy": {
    "aws.iot.SecureTunneling:mqttproxy:1": {
      "policyDescription": "Access to tunnel notification pubsub topic",
      "operations": [
        "aws.greengrass#SubscribeToIoTCore"
      ],
      "resources": [
        "$aws/things/+/tunnels/notify"
      ]
    }
  }
}
```

**Example: Configuration merge update**  
The following example configuration specifies to allow this component to open secure tunnels on a core device named **MyGreengrassCore** that runs Ubuntu.  

```
{
  "OS_DIST_INFO": "ubuntu",
  "accessControl": {
    "aws.greengrass.ipc.mqttproxy": {
      "aws.iot.SecureTunneling:mqttproxy:1": {
        "policyDescription": "Access to tunnel notification pubsub topic",
        "operations": [
          "aws.greengrass#SubscribeToIoTCore"
        ],
        "resources": [
          "$aws/things/MyGreengrassCore/tunnels/notify"
        ]
      }
    }
  }
}
```

## Local log file


This component uses the following log file.

```
/greengrass/v2/logs/aws.greengrass.SecureTunneling.log
```

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` with the path to the AWS IoT Greengrass root folder.

  ```
  sudo tail -f /greengrass/v2/logs/aws.greengrass.SecureTunneling.log
  ```

## Licenses


This component includes the following third-party software/licensing:
+ [AWS IoT Device Client](https://github.com/awslabs/aws-iot-device-client)/Apache License 2.0
+ [AWS IoT Device SDK for Java](https://github.com/aws/aws-greengrass-core-sdk-java/)/Apache License 2.0
+ [gson](https://github.com/google/gson)/Apache License 2.0
+ [log4j](https://logging.apache.org/log4j/2.x/)/Apache License 2.0
+ [slf4j](http://www.slf4j.org/)/Apache License 2.0

## Usage


To use the secure tunneling component on your device, do the following:

1. Deploy the secure tunneling component to your device.

1. Open the [AWS IoT console](https://console.aws.amazon.com/iot). From the left menu, choose **Remote actions**, and then choose **Secure tunnels**.

1. Create a tunnel to your Greengrass device. 

1. Download the source access token.

1. Use the local proxy with the source access token to connect to your destination. For more information, see [How to use the local proxy](https://docs.aws.amazon.com/iot/latest/developerguide/how-use-local-proxy.html) in the *AWS IoT Developer Guide*.

## See also

+ [AWS IoT secure tunneling](https://docs.aws.amazon.com/iot/latest/developerguide/secure-tunneling.html) in the *AWS IoT Developer Guide*
+ [How to use the local proxy](https://docs.aws.amazon.com/iot/latest/developerguide/how-use-local-proxy.html) in the *AWS IoT Developer Guide*

## Changelog


The following table describes the changes in each version of the component.


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  1.1.3  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/secure-tunneling-component.html)  | 
|  1.1.2  |   This version is no longer available. The improvements in this version are available in later versions of this component.  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/secure-tunneling-component.html)  | 
|  1.1.1  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/secure-tunneling-component.html)  | 
|  1.1.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/secure-tunneling-component.html)  | 
|  1.0.19  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/secure-tunneling-component.html)  If you are using the secure tunneling local proxy as the tunnel source client, do not update your component to this version until you have also upgraded the local proxy to version 3.1.1 or later.   | 
|  1.0.18  | Version updated for Greengrass nucleus version 2.12.0 release. | 
|  1.0.17  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/secure-tunneling-component.html)  | 
|  1.0.16  | Version updated for Greengrass nucleus version 2.11.0 release. | 
|  1.0.15  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/secure-tunneling-component.html)  | 
|  1.0.14  | Version updated for Greengrass nucleus version 2.10.0 release. | 
|  1.0.13  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/secure-tunneling-component.html)  | 
|  1.0.12  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/secure-tunneling-component.html)  | 
|  1.0.11  | Version updated for Greengrass nucleus version 2.9.0 release. | 
|  1.0.10  | Version updated for Greengrass nucleus version 2.8.0 release. | 
|  1.0.9  |  Version updated for Greengrass nucleus version 2.7.0 release.  | 
|  1.0.8  |  Version updated for Greengrass nucleus version 2.6.0 release.  | 
|  1.0.7  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/secure-tunneling-component.html)  | 
|  1.0.6  |  This version contains bug fixes.  | 
|  1.0.5  |  Version updated for Greengrass nucleus version 2.5.0 release.  | 
|  1.0.4  |  Version updated for Greengrass nucleus version 2.4.0 release.  | 
|  1.0.3  |  Version updated for Greengrass nucleus version 2.3.0 release.  | 
|  1.0.2  |  Version updated for Greengrass nucleus version 2.2.0 release.  | 
|  1.0.1  |  Version updated for Greengrass nucleus version 2.1.0 release.  | 
|  1.0.0  |  Initial version.  | 

# Shadow manager
Shadow manager v2.3.13 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html)

Shadow manager v2.3.13 is available. This release fixes an issue where local shadow updates would intermittently fail to sync to the cloud even when sync direction configuration allows it.Shadow manager v2.3.12 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html)

Shadow manager v2.3.12 is available.Shadow manager v2.3.10 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html)

Shadow manager v2.3.10 is available.Shadow manager v2.3.9 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html)

Shadow manager v2.3.9 is available.Shadow manager v2.3.8 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html)

Shadow manager v2.3.8 is available. This release fixes an issue where shadow manager creates a deadlock situation during the MQTT client connection.Shadow manager v2.3.7 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html)

Shadow manager v2.3.7 is available. This release fixes an issue where shadow manager periodically logs a `NullPointerException` error during a shadow manager sync.Shadow manager v2.3.6 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html)

Shadow manager v2.3.6 is available. This release fixes an issue where shadow properties that are deleted through AWS Cloud updates while the device is offline continue to exist in the local shadow after regaining connectivity.Shadow manager v2.3.4 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html)

Shadow manager v2.3.4 is available. This release adds support for null and empty shadow state documents.Shadow manager v2.3.1 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html)

Shadow manager v2.3.1 is available. This release fixes a condition that may prevent cloud shadow updates from syncing. This release also fixes an issue where changes to named shadow sync configuration applies to only one named shadow.Shadow manager v2.3.0 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html)

Shadow manager v2.3.0 is available. This release fixes an issue that might prevent shadows from syncing when a device stores the Greengrass device private key in a hardware security module.Shadow manager v2.2.4 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html)

Fixes an issue where the validation of the shadow's size wasn't consistent with the cloud when updating the local shadow document. This also fixes an issue where the shadow manager stops listening to configuration updates if a deployment performs a `RESET` on the configuration nodes.Shadow manager v2.1.0 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html)

Shadow manager component v2.1.0 is available. This release adds the option to configure the interval where the component syncs shadows with AWS IoT Core. For example, you can specify a longer interval to reduce bandwidth usage and charges.Shadow manager v2.0.4 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html)

Shadow manager component v2.0.4 is available. This release fixes an issue that caused shadow manager to delete newly created versions of any shadow that was previously deleted. Beginning with this release, the `DeleteThingShadow` IPC operation increments the shadow version.

The shadow manager component (`aws.greengrass.ShadowManager`) enables the local shadow service on your core device. The local shadow service allows components to use interprocess communication to [interact with local shadows](ipc-local-shadows.md). The shadow manager component manages the storage of local shadow documents, and also handles synchronization of local shadow states with the AWS IoT Device Shadow service.

For more information about how Greengrass core devices can interact with shadows, see [Interact with device shadows](interact-with-shadows.md).

**Topics**
+ [

## Versions
](#shadow-manager-component-versions)
+ [

## Type
](#shadow-manager-component-type)
+ [

## Operating system
](#shadow-manager-component-os-support)
+ [

## Requirements
](#shadow-manager-component-requirements)
+ [

## Dependencies
](#shadow-manager-component-dependencies)
+ [

## Configuration
](#shadow-manager-component-configuration)
+ [

## Local log file
](#shadow-manager-component-log-file)
+ [

## Changelog
](#shadow-manager-component-changelog)

## Versions


This component has the following versions:
+ 2.3.x
+ 2.2.x
+ 2.1.x
+ 2.0.x

## Type


<a name="public-component-type-plugin-para1"></a>This component is a plugin component (`aws.greengrass.plugin`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs this component in the same Java Virtual Machine (JVM) as the nucleus. The nucleus restarts when you change this component's version on the core device.

<a name="public-component-type-plugin-para2"></a>This component uses the same log file as the Greengrass nucleus. For more information, see [Monitor AWS IoT Greengrass logs](monitor-logs.md).

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on core devices that run the following operating systems:
+ Linux
+ Windows

## Requirements


This component has the following requirements:
+ (Optional) To sync shadows to the AWS IoT Device Shadow service, the Greengrass core device's AWS IoT policy must allow the following AWS IoT Core shadow policy actions:
  + `iot:GetThingShadow`
  + `iot:UpdateThingShadow`
  + `iot:DeleteThingShadow`

  For more information about these AWS IoT Core policies, see [AWS IoT Core policy actions](https://docs.aws.amazon.com/iot/latest/developerguide/iot-policy-actions.html) in the *AWS IoT Developer Guide*.

  For more information about the minimal AWS IoT policy, see [Minimal AWS IoT policy for AWS IoT Greengrass V2 core devices](device-auth.md#greengrass-core-minimal-iot-policy)
+ The shadow manager component is supported to run in a VPC.

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#shadow-manager-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

------
#### [ 2.3.13 ]

The following table lists the dependencies for version 2.3.13 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.0 <2.17.0 | Soft | 

------
#### [ 2.3.12 ]

The following table lists the dependencies for version 2.3.12 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.0 <2.17.0 | Soft | 

------
#### [ 2.3.11 ]

The following table lists the dependencies for version 2.3.11 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.0 <2.16.0 | Soft | 

------
#### [ 2.3.10 ]

The following table lists the dependencies for version 2.3.10 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.0 <2.15.0 | Soft | 

------
#### [ 2.3.9 ]

The following table lists the dependencies for version 2.3.9 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.0 <2.14.0 | Soft | 

------
#### [ 2.3.5 – 2.3.8 ]

The following table lists the dependencies for versions 2.3.5 through 2.3.8 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.0 <2.13.0 | Soft | 

------
#### [ 2.3.3 and 2.3.4 ]

The following table lists the dependencies for versions 2.3.3 and 2.3.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.0 <2.12.0 | Soft | 

------
#### [ 2.3.2 ]

The following table lists the dependencies for version 2.3.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.0 <2.11.0 | Soft | 

------
#### [ 2.3.0 and 2.3.1 ]

The following table lists the dependencies for versions 2.3.0 and 2.3.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.5.0 <2.10.0 | Soft | 

------
#### [ 2.2.3 and 2.2.4 ]

The following table lists the dependencies for versions 2.2.3 and 2.2.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.2.0 <3.0.0 | Soft | 

------
#### [ 2.2.2 ]

The following table lists the dependencies for version 2.2.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.2.0 <2.9.0 | Soft | 

------
#### [ 2.2.1 ]

The following table lists the dependencies for version 2.2.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.2.0 <2.8.0 | Soft | 

------
#### [ 2.1.1 and 2.2.0 ]

The following table lists the dependencies for versions 2.1.1 and 2.2.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.2.0 <2.7.0 | Soft | 

------
#### [ 2.0.5 - 2.1.0 ]

The following table lists the dependencies for versions 2.0.5 through 2.1.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.2.0 <2.6.0 | Soft | 

------
#### [ 2.0.3 and 2.0.4 ]

The following table lists the dependencies for versions 2.0.3 and 2.0.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.2.0 <2.5.0 | Soft | 

------
#### [ 2.0.1 and 2.0.2 ]

The following table lists the dependencies for versions 2.0.1 and 2.0.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.2.0 <2.4.0 | Soft | 

------
#### [ 2.0.0 ]

The following table lists the dependencies for version 2.0.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.2.0 <2.3.0 | Soft | 

------

For more information about component dependencies, see the [component recipe reference](component-recipe-reference.md#recipe-reference-component-dependencies).

## Configuration


This component provides the following configuration parameters that you can customize when you deploy the component.

------
#### [ 2.3.x ]

`strategy`  <a name="shadow-manager-component-configuration-strategy"></a>
(Optional) The strategy that this component uses to sync shadows between AWS IoT Core and the core device.  
This object contains the following information.    
`type`  
(Optional) The type of strategy that this component uses to sync shadows between AWS IoT Core and the core device. Choose from the following options:  
+ `realTime` – Sync shadows with AWS IoT Core each time a shadow update occurs.
+ `periodic` – Sync shadows with AWS IoT Core on a regular interval that you specify with the `delay` configuration parameter.
Default: `realTime`  
`delay`  
(Optional) The interval in seconds where this component syncs shadows with AWS IoT Core, when you specify the `periodic` sync strategy.  
This parameter is required if you specify the `periodic` sync strategy.

`synchronize`  <a name="shadow-manager-component-configuration-synchronize"></a>
<a name="shadow-manager-component-configuration-strategy-description"></a>(Optional) The synchronization settings that determine how shadows are synced with the AWS Cloud.   
You must create a configuration update with this property to sync shadows with the AWS Cloud.
This object contains the following information.    
`coreThing`  <a name="shadow-manager-component-configuration-synchronize-core-thing"></a>
(Optional) The core device shadows to sync. This object contains the following information.    
`classic`  
(Optional) By default, the shadow manager syncs the local state of the classic shadow for your core device with the AWS Cloud. If you don't want to sync the classic device shadow, set this to `false`.  
Default: `true`  
`namedShadows`  
(Optional) The list of named core device shadows to sync. You must specify the exact names of the shadows.  
The AWS IoT Greengrass service uses the `AWSManagedGreengrassV2Deployment` named shadow to manage deployments that target individual core devices. This named shadow is reserved for use by the AWS IoT Greengrass service. Do not update or delete this named shadow.  
`shadowDocumentsMap`  <a name="shadow-manager-component-configuration-synchronize-shadow-documents-map"></a>
(Optional) The additional device shadows to sync. Using this configuration parameter makes it easier to specify shadow documents. We recommend that you use this parameter instead of the `shadowDocuments` object.  
If you specify a `shadowDocumentsMap` object, you must not specify a `shadowDocuments` object.
Each object contains the following information:    
*`thingName`*  
The shadow configuration for the *thingName* for this shadow configuration.    
`classic`  
(Optional) If you don't want to sync the classic device shadow for the `thingName` device, set this to `false`.  
`namedShadows`  
The list of named shadows that you want to sync. You must specify the exact names of the shadows.  
`shadowDocuments`  <a name="shadow-manager-component-configuration-synchronize-shadow-documents"></a>
(Optional) The list of additional device shadows to sync. We recommend that you use the `shadowDocumentsMap` parameter instead.  
If you specify a `shadowDocuments` object, you must not specify a `shadowDocumentsMap` object.
Each object in this list contains the following information.     
`thingName`  
The thing name of the device for which to sync shadows.   
`classic`  
(Optional) If you don't want to sync the classic device shadow for the `thingName` device, set this to `false`.  
Default: `true`  
`namedShadows`  
(Optional) The list of named device shadows that you want to sync. You must specify the exact names of the shadows.  
`direction`  
(Optional) The direction to sync shadows between the local shadow service and the AWS Cloud. You can configure this option to reduce bandwidth and connections to the AWS Cloud. Choose from the following options:  
+ `betweenDeviceAndCloud` – Synchronize shadows between the local shadow service and the AWS Cloud.
+ `deviceToCloud` – Send shadow updates from the local shadow service to the AWS Cloud, and ignore shadow updates from the AWS Cloud.
+ `cloudToDevice` – Receive shadow updates from the AWS Cloud, and don't send shadow updates from the local shadow service to the AWS Cloud.
Default: `BETWEEN_DEVICE_AND_CLOUD`

`rateLimits`  <a name="shadow-manager-component-configuration-rate-limits"></a>
(Optional) The settings that determine the rate limits for shadow service requests.  
This object contains the following information.    
`maxOutboundSyncUpdatesPerSecond`  
(Optional) The maximum number of sync requests per second that the device transmits.   
Default: 100 requests/second  
`maxTotalLocalRequestsRate`  
(Optional) The maximum number of local IPC requests per second that are sent to the core device.   
Default: 200 requests/second  
`maxLocalRequestsPerSecondPerThing`  
(Optional) The maximum number of local IPC requests per second that are sent for each connected IoT thing.   
Default: 20 requests/second for each thing
These rate limits parameters define the maximum number of requests per second for the local shadow service. The maximum number of requests per second for the AWS IoT Device Shadow service depends on your AWS Region. For more information, see the limits for the [AWS IoT Device Shadow Service API](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#device-shadow-limits) in the *Amazon Web Services General Reference*.

`shadowDocumentSizeLimitBytes`  <a name="shadow-manager-component-configuration-shadow-document-size-limit-bytes"></a>
(Optional) The maximum allowed size of each JSON state document for local shadows.   
If you increase this value, you must also increase the resource limit for the JSON state document for cloud shadows. For more information, see the limits for the [AWS IoT Device Shadow Service API](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#device-shadow-limits) in the *Amazon Web Services General Reference*.  
Default: 8192 bytes  
Maximum: 30720 bytes

**Example: Configuration merge update**  
The following example shows a sample configuration merge update with all available configuration parameters for the shadow manager component.  

```
{
   "strategy":{
      "type":"periodic",
      "delay":300
   },
   "synchronize":{
      "shadowDocumentsMap":{
         "MyDevice1":{
            "classic":false,
            "namedShadows":[
               "MyShadowA",
               "MyShadowB"
            ]
         },
         "MyDevice2":{
            "classic":true,
            "namedShadows":[]
         }
      },
      "direction":"betweenDeviceAndCloud"
   },
   "rateLimits":{
      "maxOutboundSyncUpdatesPerSecond":100,
      "maxTotalLocalRequestsRate":200,
      "maxLocalRequestsPerSecondPerThing":20
   },
   "shadowDocumentSizeLimitBytes":8192
}
```

------
#### [ 2.2.x ]

`strategy`  <a name="shadow-manager-component-configuration-strategy"></a>
(Optional) The strategy that this component uses to sync shadows between AWS IoT Core and the core device.  
This object contains the following information.    
`type`  
(Optional) The type of strategy that this component uses to sync shadows between AWS IoT Core and the core device. Choose from the following options:  
+ `realTime` – Sync shadows with AWS IoT Core each time a shadow update occurs.
+ `periodic` – Sync shadows with AWS IoT Core on a regular interval that you specify with the `delay` configuration parameter.
Default: `realTime`  
`delay`  
(Optional) The interval in seconds where this component syncs shadows with AWS IoT Core, when you specify the `periodic` sync strategy.  
This parameter is required if you specify the `periodic` sync strategy.

`synchronize`  <a name="shadow-manager-component-configuration-synchronize"></a>
<a name="shadow-manager-component-configuration-strategy-description"></a>(Optional) The synchronization settings that determine how shadows are synced with the AWS Cloud.   
You must create a configuration update with this property to sync shadows with the AWS Cloud.
This object contains the following information.    
`coreThing`  <a name="shadow-manager-component-configuration-synchronize-core-thing"></a>
(Optional) The core device shadows to sync. This object contains the following information.    
`classic`  
(Optional) By default, the shadow manager syncs the local state of the classic shadow for your core device with the AWS Cloud. If you don't want to sync the classic device shadow, set this to `false`.  
Default: `true`  
`namedShadows`  
(Optional) The list of named core device shadows to sync. You must specify the exact names of the shadows.  
The AWS IoT Greengrass service uses the `AWSManagedGreengrassV2Deployment` named shadow to manage deployments that target individual core devices. This named shadow is reserved for use by the AWS IoT Greengrass service. Do not update or delete this named shadow.  
`shadowDocumentsMap`  <a name="shadow-manager-component-configuration-synchronize-shadow-documents-map"></a>
(Optional) The additional device shadows to sync. Using this configuration parameter makes it easier to specify shadow documents. We recommend that you use this parameter instead of the `shadowDocuments` object.  
If you specify a `shadowDocumentsMap` object, you must not specify a `shadowDocuments` object.
Each object contains the following information:    
*`thingName`*  
The shadow configuration for the *thingName* for this shadow configuration.    
`classic`  
(Optional) If you don't want to sync the classic device shadow for the `thingName` device, set this to `false`.  
`namedShadows`  
The list of named shadows that you want to sync. You must specify the exact names of the shadows.  
`shadowDocuments`  <a name="shadow-manager-component-configuration-synchronize-shadow-documents"></a>
(Optional) The list of additional device shadows to sync. We recommend that you use the `shadowDocumentsMap` parameter instead.  
If you specify a `shadowDocuments` object, you must not specify a `shadowDocumentsMap` object.
Each object in this list contains the following information.     
`thingName`  
The thing name of the device for which to sync shadows.   
`classic`  
(Optional) If you don't want to sync the classic device shadow for the `thingName` device, set this to `false`.  
Default: `true`  
`namedShadows`  
(Optional) The list of named device shadows that you want to sync. You must specify the exact names of the shadows.  
`direction`  
(Optional) The direction to sync shadows between the local shadow service and the AWS Cloud. You can configure this option to reduce bandwidth and connections to the AWS Cloud. Choose from the following options:  
+ `betweenDeviceAndCloud` – Synchronize shadows between the local shadow service and the AWS Cloud.
+ `deviceToCloud` – Send shadow updates from the local shadow service to the AWS Cloud, and ignore shadow updates from the AWS Cloud.
+ `cloudToDevice` – Receive shadow updates from the AWS Cloud, and don't send shadow updates from the local shadow service to the AWS Cloud.
Default: `BETWEEN_DEVICE_AND_CLOUD`

`rateLimits`  <a name="shadow-manager-component-configuration-rate-limits"></a>
(Optional) The settings that determine the rate limits for shadow service requests.  
This object contains the following information.    
`maxOutboundSyncUpdatesPerSecond`  
(Optional) The maximum number of sync requests per second that the device transmits.   
Default: 100 requests/second  
`maxTotalLocalRequestsRate`  
(Optional) The maximum number of local IPC requests per second that are sent to the core device.   
Default: 200 requests/second  
`maxLocalRequestsPerSecondPerThing`  
(Optional) The maximum number of local IPC requests per second that are sent for each connected IoT thing.   
Default: 20 requests/second for each thing
These rate limits parameters define the maximum number of requests per second for the local shadow service. The maximum number of requests per second for the AWS IoT Device Shadow service depends on your AWS Region. For more information, see the limits for the [AWS IoT Device Shadow Service API](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#device-shadow-limits) in the *Amazon Web Services General Reference*.

`shadowDocumentSizeLimitBytes`  <a name="shadow-manager-component-configuration-shadow-document-size-limit-bytes"></a>
(Optional) The maximum allowed size of each JSON state document for local shadows.   
If you increase this value, you must also increase the resource limit for the JSON state document for cloud shadows. For more information, see the limits for the [AWS IoT Device Shadow Service API](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#device-shadow-limits) in the *Amazon Web Services General Reference*.  
Default: 8192 bytes  
Maximum: 30720 bytes

**Example: Configuration merge update**  
The following example shows a sample configuration merge update with all available configuration parameters for the shadow manager component.  

```
{
   "strategy":{
      "type":"periodic",
      "delay":300
   },
   "synchronize":{
      "shadowDocumentsMap":{
         "MyDevice1":{
            "classic":false,
            "namedShadows":[
               "MyShadowA",
               "MyShadowB"
            ]
         },
         "MyDevice2":{
            "classic":true,
            "namedShadows":[]
         }
      },
      "direction":"betweenDeviceAndCloud"
   },
   "rateLimits":{
      "maxOutboundSyncUpdatesPerSecond":100,
      "maxTotalLocalRequestsRate":200,
      "maxLocalRequestsPerSecondPerThing":20
   },
   "shadowDocumentSizeLimitBytes":8192
}
```

------
#### [ 2.1.x ]

`strategy`  <a name="shadow-manager-component-configuration-strategy"></a>
(Optional) The strategy that this component uses to sync shadows between AWS IoT Core and the core device.  
This object contains the following information.    
`type`  
(Optional) The type of strategy that this component uses to sync shadows between AWS IoT Core and the core device. Choose from the following options:  
+ `realTime` – Sync shadows with AWS IoT Core each time a shadow update occurs.
+ `periodic` – Sync shadows with AWS IoT Core on a regular interval that you specify with the `delay` configuration parameter.
Default: `realTime`  
`delay`  
(Optional) The interval in seconds where this component syncs shadows with AWS IoT Core, when you specify the `periodic` sync strategy.  
This parameter is required if you specify the `periodic` sync strategy.

`synchronize`  <a name="shadow-manager-component-configuration-synchronize"></a>
<a name="shadow-manager-component-configuration-strategy-description"></a>(Optional) The synchronization settings that determine how shadows are synced with the AWS Cloud.   
You must create a configuration update with this property to sync shadows with the AWS Cloud.
This object contains the following information.    
`coreThing`  <a name="shadow-manager-component-configuration-synchronize-core-thing"></a>
(Optional) The core device shadows to sync. This object contains the following information.    
`classic`  
(Optional) By default, the shadow manager syncs the local state of the classic shadow for your core device with the AWS Cloud. If you don't want to sync the classic device shadow, set this to `false`.  
Default: `true`  
`namedShadows`  
(Optional) The list of named core device shadows to sync. You must specify the exact names of the shadows.  
The AWS IoT Greengrass service uses the `AWSManagedGreengrassV2Deployment` named shadow to manage deployments that target individual core devices. This named shadow is reserved for use by the AWS IoT Greengrass service. Do not update or delete this named shadow.  
`shadowDocumentsMap`  <a name="shadow-manager-component-configuration-synchronize-shadow-documents-map"></a>
(Optional) The additional device shadows to sync. Using this configuration parameter makes it easier to specify shadow documents. We recommend that you use this parameter instead of the `shadowDocuments` object.  
If you specify a `shadowDocumentsMap` object, you must not specify a `shadowDocuments` object.
Each object contains the following information:    
*`thingName`*  
The shadow configuration for the *thingName* for this shadow configuration.    
`classic`  
(Optional) If you don't want to sync the classic device shadow for the `thingName` device, set this to `false`.  
`namedShadows`  
The list of named shadows that you want to sync. You must specify the exact names of the shadows.  
`shadowDocuments`  <a name="shadow-manager-component-configuration-synchronize-shadow-documents"></a>
(Optional) The list of additional device shadows to sync. We recommend that you use the `shadowDocumentsMap` parameter instead.  
If you specify a `shadowDocuments` object, you must not specify a `shadowDocumentsMap` object.
Each object in this list contains the following information.     
`thingName`  
The thing name of the device for which to sync shadows.   
`classic`  
(Optional) If you don't want to sync the classic device shadow for the `thingName` device, set this to `false`.  
Default: `true`  
`namedShadows`  
(Optional) The list of named device shadows that you want to sync. You must specify the exact names of the shadows.

`rateLimits`  <a name="shadow-manager-component-configuration-rate-limits"></a>
(Optional) The settings that determine the rate limits for shadow service requests.  
This object contains the following information.    
`maxOutboundSyncUpdatesPerSecond`  
(Optional) The maximum number of sync requests per second that the device transmits.   
Default: 100 requests/second  
`maxTotalLocalRequestsRate`  
(Optional) The maximum number of local IPC requests per second that are sent to the core device.   
Default: 200 requests/second  
`maxLocalRequestsPerSecondPerThing`  
(Optional) The maximum number of local IPC requests per second that are sent for each connected IoT thing.   
Default: 20 requests/second for each thing
These rate limits parameters define the maximum number of requests per second for the local shadow service. The maximum number of requests per second for the AWS IoT Device Shadow service depends on your AWS Region. For more information, see the limits for the [AWS IoT Device Shadow Service API](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#device-shadow-limits) in the *Amazon Web Services General Reference*.

`shadowDocumentSizeLimitBytes`  <a name="shadow-manager-component-configuration-shadow-document-size-limit-bytes"></a>
(Optional) The maximum allowed size of each JSON state document for local shadows.   
If you increase this value, you must also increase the resource limit for the JSON state document for cloud shadows. For more information, see the limits for the [AWS IoT Device Shadow Service API](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#device-shadow-limits) in the *Amazon Web Services General Reference*.  
Default: 8192 bytes  
Maximum: 30720 bytes

**Example: Configuration merge update**  
The following example shows a sample configuration merge update with all available configuration parameters for the shadow manager component.  

```
{
   "strategy":{
      "type":"periodic",
      "delay":300
   },
   "synchronize":{
      "shadowDocumentsMap":{
         "MyDevice1":{
            "classic":false,
            "namedShadows":[
               "MyShadowA",
               "MyShadowB"
            ]
         },
         "MyDevice2":{
            "classic":true,
            "namedShadows":[]
         }
      },
      "direction":"betweenDeviceAndCloud"
   },
   "rateLimits":{
      "maxOutboundSyncUpdatesPerSecond":100,
      "maxTotalLocalRequestsRate":200,
      "maxLocalRequestsPerSecondPerThing":20
   },
   "shadowDocumentSizeLimitBytes":8192
}
```

------
#### [ 2.0.x ]

`synchronize`  <a name="shadow-manager-component-configuration-synchronize"></a>
<a name="shadow-manager-component-configuration-strategy-description"></a>(Optional) The synchronization settings that determine how shadows are synced with the AWS Cloud.   
You must create a configuration update with this property to sync shadows with the AWS Cloud.
This object contains the following information.    
`coreThing`  <a name="shadow-manager-component-configuration-synchronize-core-thing"></a>
(Optional) The core device shadows to sync. This object contains the following information.    
`classic`  
(Optional) By default, the shadow manager syncs the local state of the classic shadow for your core device with the AWS Cloud. If you don't want to sync the classic device shadow, set this to `false`.  
Default: `true`  
`namedShadows`  
(Optional) The list of named core device shadows to sync. You must specify the exact names of the shadows.  
The AWS IoT Greengrass service uses the `AWSManagedGreengrassV2Deployment` named shadow to manage deployments that target individual core devices. This named shadow is reserved for use by the AWS IoT Greengrass service. Do not update or delete this named shadow.  
`shadowDocumentsMap`  <a name="shadow-manager-component-configuration-synchronize-shadow-documents-map"></a>
(Optional) The additional device shadows to sync. Using this configuration parameter makes it easier to specify shadow documents. We recommend that you use this parameter instead of the `shadowDocuments` object.  
If you specify a `shadowDocumentsMap` object, you must not specify a `shadowDocuments` object.
Each object contains the following information:    
*`thingName`*  
The shadow configuration for the *thingName* for this shadow configuration.    
`classic`  
(Optional) If you don't want to sync the classic device shadow for the `thingName` device, set this to `false`.  
`namedShadows`  
The list of named shadows that you want to sync. You must specify the exact names of the shadows.  
`shadowDocuments`  <a name="shadow-manager-component-configuration-synchronize-shadow-documents"></a>
(Optional) The list of additional device shadows to sync. We recommend that you use the `shadowDocumentsMap` parameter instead.  
If you specify a `shadowDocuments` object, you must not specify a `shadowDocumentsMap` object.
Each object in this list contains the following information.     
`thingName`  
The thing name of the device for which to sync shadows.   
`classic`  
(Optional) If you don't want to sync the classic device shadow for the `thingName` device, set this to `false`.  
Default: `true`  
`namedShadows`  
(Optional) The list of named device shadows that you want to sync. You must specify the exact names of the shadows.

`rateLimits`  <a name="shadow-manager-component-configuration-rate-limits"></a>
(Optional) The settings that determine the rate limits for shadow service requests.  
This object contains the following information.    
`maxOutboundSyncUpdatesPerSecond`  
(Optional) The maximum number of sync requests per second that the device transmits.   
Default: 100 requests/second  
`maxTotalLocalRequestsRate`  
(Optional) The maximum number of local IPC requests per second that are sent to the core device.   
Default: 200 requests/second  
`maxLocalRequestsPerSecondPerThing`  
(Optional) The maximum number of local IPC requests per second that are sent for each connected IoT thing.   
Default: 20 requests/second for each thing
These rate limits parameters define the maximum number of requests per second for the local shadow service. The maximum number of requests per second for the AWS IoT Device Shadow service depends on your AWS Region. For more information, see the limits for the [AWS IoT Device Shadow Service API](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#device-shadow-limits) in the *Amazon Web Services General Reference*.

`shadowDocumentSizeLimitBytes`  <a name="shadow-manager-component-configuration-shadow-document-size-limit-bytes"></a>
(Optional) The maximum allowed size of each JSON state document for local shadows.   
If you increase this value, you must also increase the resource limit for the JSON state document for cloud shadows. For more information, see the limits for the [AWS IoT Device Shadow Service API](https://docs.aws.amazon.com/general/latest/gr/iot-core.html#device-shadow-limits) in the *Amazon Web Services General Reference*.  
Default: 8192 bytes  
Maximum: 30720 bytes

**Example: Configuration merge update**  
The following example shows a sample configuration merge update with all available configuration parameters for the shadow manager component.  

```
{
  "synchronize": {
    "coreThing": {
      "classic": true,
      "namedShadows": [
        "MyCoreShadowA",
        "MyCoreShadowB"
      ]
    },
    "shadowDocuments": [
      {
        "thingName": "MyDevice1",
        "classic": false,
        "namedShadows": [
          "MyShadowA",
          "MyShadowB"
        ]
      },
      {
        "thingName": "MyDevice2",
        "classic": true,
        "namedShadows": []
      }
    ]
  },
  "rateLimits": {       
    "maxOutboundSyncUpdatesPerSecond": 100,
    "maxTotalLocalRequestsRate": 200,
    "maxLocalRequestsPerSecondPerThing": 20
  },
  "shadowDocumentSizeLimitBytes": 8192
}
```

------

## Local log file


This component uses the same log file as the [Greengrass nucleus](greengrass-nucleus-component.md) component.

------
#### [ Linux ]

```
/greengrass/v2/logs/greengrass.log
```

------
#### [ Windows ]

```
C:\greengrass\v2\logs\greengrass.log
```

------

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the path to the AWS IoT Greengrass root folder.

------
#### [ Linux ]

  ```
  sudo tail -f /greengrass/v2/logs/greengrass.log
  ```

------
#### [ Windows (PowerShell) ]

  ```
  Get-Content C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
  ```

------

## Changelog


The following table describes the changes in each version of the component.


|  Version  |  Changes  | 
| --- | --- | 
|  2.3.13  | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html) | 
|  2.3.12  | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html) | 
|  2.3.11  | Version updated for Greengrass nucleus version 2.15.0 release. | 
|  2.3.10  | Version updated for Greengrass nucleus version 2.14.0 release. | 
|  2.3.9  | Version updated for Greengrass nucleus version 2.13.0 release. | 
|  2.3.8  | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html) | 
|  2.3.7  | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html) | 
|  2.3.6  | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html) | 
|  2.3.5  | Version updated for Greengrass nucleus version 2.12.0 release. | 
|  2.3.4  |  <a name="changelog-shadow-manager-2.3.4"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html)  | 
|  2.3.3  | Version updated for Greengrass nucleus version 2.11.0 release. | 
|  2.3.2  | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html) | 
|  2.3.1  | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html) | 
|  2.3.0  | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html) | 
|  2.2.4  | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html) | 
|  2.2.3  | Version updated for Greengrass nucleus version 2.9.0 release. | 
|  2.2.2  | Version updated for Greengrass nucleus version 2.8.0 release. | 
|  2.2.1  |  Version updated for Greengrass nucleus version 2.7.0 release.  | 
|  2.2.0  |  <a name="changelog-shadow-manager-2.2.0"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html)  | 
|  2.1.1  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html)  | 
|  2.1.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html)  | 
|  2.0.6  |  This version contains bug fixes and improvements.  | 
|  2.0.5  |  Version updated for Greengrass nucleus version 2.5.0 release.  | 
|  2.0.4  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html)  | 
|  2.0.3  |  Version updated for Greengrass nucleus version 2.4.0 release.  | 
|  2.0.2  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/shadow-manager-component.html)  | 
|  2.0.1  |  Version updated for Greengrass nucleus version 2.3.0 release.  | 
|  2.0.0  |  Initial version.  | 

# Amazon SNS


The Amazon SNS component (`aws.greengrass.SNS`) publishes messages to an Amazon Simple Notification Service (Amazon SNS) topic. You can use this component to send events from Greengrass core devices to web servers, email addresses, and other message subscribers. For more information, see [What is Amazon SNS?](https://docs.aws.amazon.com/sns/latest/dg/welcome.html) in the *Amazon Simple Notification Service Developer Guide*.

To publish to an Amazon SNS topic with this component, publish a message to the topic where this component subscribes. By default, this component subscribes to the `sns/message` [local publish/subscribe](ipc-publish-subscribe.md) topic. You can specify other topics, including AWS IoT Core MQTT topics, when you deploy this component.

In your custom component, you might want to implement filtering or formatting logic to process messages from other sources before you publish them to this component. This enables you to centralize your message processing logic on a single component.

**Note**  
This component provides similar functionality to the Amazon SNS connector in AWS IoT Greengrass V1. For more information, see [Amazon SNS connector](https://docs.aws.amazon.com/greengrass/latest/developerguide/sns-connector.html) in the *AWS IoT Greengrass V1 Developer Guide*.

**Topics**
+ [

## Versions
](#sns-component-versions)
+ [

## Type
](#sns-component-type)
+ [

## Operating system
](#sns-component-os-support)
+ [

## Requirements
](#sns-component-requirements)
+ [

## Dependencies
](#sns-component-dependencies)
+ [

## Configuration
](#sns-component-configuration)
+ [

## Input data
](#sns-component-input-data)
+ [

## Output data
](#sns-component-output-data)
+ [

## Local log file
](#sns-component-log-file)
+ [

## Licenses
](#sns-component-licenses)
+ [

## Changelog
](#sns-component-changelog)

## Versions


This component has the following versions:
+ 2.1.x
+ 2.0.x

## Type


<a name="public-component-type-lambda"></a>This <a name="public-component-type-lambda-phrase"></a>component is a Lambda component (`aws.greengrass.lambda`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs this component's Lambda function using the [Lambda launcher component](lambda-launcher-component.md).

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on Linux core devices only.

## Requirements


This component has the following requirements:
+ <a name="core-device-lambda-function-requirements"></a>Your core device must meet the requirements to run Lambda functions. If you want the core device to run containerized Lambda functions, the device must meet the requirements to do so. For more information, see [Lambda function requirements](setting-up.md#greengrass-v2-lambda-requirements).
+ <a name="public-component-python3-requirement"></a>[Python](https://www.python.org/) version 3.7 installed on the core device and added to the PATH environment variable.
+ An Amazon SNS topic. For more information, see [Creating an Amazon SNS topic](https://docs.aws.amazon.com/sns/latest/dg/sns-create-topic.html) in the *Amazon Simple Notification Service Developer Guide*.
+ The [Greengrass device role](device-service-role.md) must allow the `sns:Publish` action, as shown in the following example IAM policy.

------
#### [ JSON ]

****  

  ```
  {
    "Version":"2012-10-17",		 	 	 
    "Statement": [
      {
        "Action": [
          "sns:Publish"
        ],
        "Effect": "Allow",
        "Resource": [
          "arn:aws:sns:us-east-1:123456789012:topic-name"
        ]
      }
    ]
  }
  ```

------

  You can dynamically override the default topic in the input message payload for this component. If your application uses this feature, the IAM policy must include all target topics as resources. You can grant granular or conditional access to resources (for example, by using a wildcard `*` naming scheme).
+ <a name="connector-component-legacy-subscription-router-dependency"></a>To receive output data from this component, you must merge the following configuration update for the [legacy subscription router component](legacy-subscription-router-component.md) (`aws.greengrass.LegacySubscriptionRouter`) when you deploy this component. This configuration specifies the topic where this component publishes responses.

------
#### [ Legacy subscription router v2.1.x ]

  ```
  {
    "subscriptions": {
      "aws-greengrass-sns": {
        "id": "aws-greengrass-sns",
        "source": "component:aws.greengrass.SNS",
        "subject": "sns/message/status",
        "target": "cloud"
      }
    }
  }
  ```

------
#### [ Legacy subscription router v2.0.x ]

  ```
  {
    "subscriptions": {
      "aws-greengrass-sns": {
        "id": "aws-greengrass-sns",
        "source": "arn:aws:lambda:region:aws:function:aws-greengrass-sns:version",
        "subject": "sns/message/status",
        "target": "cloud"
      }
    }
  }
  ```<a name="connector-component-legacy-subscription-router-dependency-replace"></a>
  + Replace *region* with the AWS Region that you use.
  + Replace *version* with the version of the Lambda function that this component runs. To find the Lambda function version, you must view the recipe for the version of this component that you want to deploy. Open this component's details page in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass), and look for the **Lambda function** key-value pair. This key-value pair contains the name and version of the Lambda function.

**Important**  <a name="connector-component-legacy-subscription-router-dependency-note"></a>
You must update the Lambda function version on the legacy subscription router every time you deploy this component. This ensures that you use the correct Lambda function version for the component version that you deploy.

------

  <a name="connector-component-create-deployments"></a>For more information, see [Create deployments](create-deployments.md).
+ The Amazon SNS component is supported to run in a VPC. To deploy this component in a VPC, the following is required.
  + The Amazon SNS component must have connectivity to `sns.region.amazonaws.com` which has the VPC endpoint of `com.amazonaws.us-east-1.sns`.

### Endpoints and ports


This component must be able to perform outbound requests to the following endpoints and ports, in addition to endpoints and ports required for basic operation. For more information, see [Allow device traffic through a proxy or firewall](allow-device-traffic.md).


| Endpoint | Port | Required | Description | 
| --- | --- | --- | --- | 
|  `sns.region.amazonaws.com`  | 443 | Yes |  Publish messages to Amazon SNS.  | 

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#sns-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

------
#### [ 2.1.10 ]

The following table lists the dependencies for version 2.1.10 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.16.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.1.9 ]

The following table lists the dependencies for version 2.1.9 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.15.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.1.8 ]

The following table lists the dependencies for version 2.1.8 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.14.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.1.7 ]

The following table lists the dependencies for version 2.1.7 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.13.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.1.6 ]

The following table lists the dependencies for version 2.1.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.12.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.1.5 ]

The following table lists the dependencies for version 2.1.5 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.11.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.1.4 ]

The following table lists the dependencies for version 2.1.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.10.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.1.3 ]

The following table lists the dependencies for version 2.1.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.9.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.1.2 ]

The following table lists the dependencies for version 2.1.2 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.8.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.1.1 ]

The following table lists the dependencies for version 2.1.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.7.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.0.8 - 2.1.0 ]

The following table lists the dependencies for versions 2.0.8 and 2.1.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.6.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.0.7 ]

The following table lists the dependencies for version 2.0.7 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.5.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.0.6 ]

The following table lists the dependencies for version 2.0.6 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.4.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.0.5 ]

The following table lists the dependencies for version 2.0.5 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.3.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.0.4 ]

The following table lists the dependencies for version 2.0.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.0 <2.2.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | ^2.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | ^2.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | ^2.0.0  | Hard | 

------
#### [ 2.0.3 ]

The following table lists the dependencies for version 2.0.3 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.0.3 <2.1.0  | Hard | 
| [Lambda launcher](lambda-launcher-component.md) | >=1.0.0  | Hard | 
| [Lambda runtimes](lambda-runtimes-component.md) | >=1.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) | >=1.0.0  | Hard | 

------

For more information about component dependencies, see the [component recipe reference](component-recipe-reference.md#recipe-reference-component-dependencies).

## Configuration


This component provides the following configuration parameters that you can customize when you deploy the component.

**Note**  <a name="connector-component-lambda-parameters"></a>
This component's default configuration includes Lambda function parameters. We recommend that you edit only the following parameters to configure this component on your devices.

`lambdaParams`  
An object that contains the parameters for this component's Lambda function. This object contains the following information:    
`EnvironmentVariables`  
An object that contains the Lambda function's parameters. This object contains the following information:    
`DEFAULT_SNS_ARN`  
The ARN of the default Amazon SNS topic where this component publishes messages. You can override the destination topic with the `sns_topic_arn` property in the input message payload.

`containerMode`  <a name="connector-component-container-mode-parameter"></a>
(Optional) The containerization mode for this component. Choose from the following options:  <a name="lambda-function-component-container-mode-parameter"></a>
+ `NoContainer` – The component doesn't run in an isolated runtime environment.
+ `GreengrassContainer` – The component runs in an isolated runtime environment inside the AWS IoT Greengrass container.
Default: `GreengrassContainer`

`containerParams`  
<a name="connector-component-container-params-description"></a>(Optional) An object that contains the container parameters for this component. The component uses these parameters if you specify `GreengrassContainer` for `containerMode`.  
This object contains the following information:    
`memorySize`  
<a name="connector-component-container-params-memory-size-description"></a>(Optional) The amount of memory (in kilobytes) to allocate to the component.  
Defaults to 512 MB (525,312 KB).

`pubsubTopics`  <a name="connector-component-pubsub-topics-parameter"></a>
(Optional) An object that contains the topics where the component subscribes to receive messages. You can specify each topic and whether the component subscribes to MQTT topics from AWS IoT Core or local publish/subscribe topics.  
This object contains the following information:    
`0` – This is an array index as a string.  
An object that contains the following information:    
`type`  
(Optional) The type of publish/subscribe messaging that this component uses to subscribe to messages. Choose from the following options:  
+ `PUB_SUB` – Subscribe to local publish/subscribe messages. If you choose this option, the topic can't contain MQTT wildcards. For more information about how to send messages from custom component when you specify this option, see [Publish/subscribe local messages](ipc-publish-subscribe.md).
+ `IOT_CORE` – Subscribe to AWS IoT Core MQTT messages. If you choose this option, the topic can contain MQTT wildcards. For more information about how to send messages from custom components when you specify this option, see [Publish/subscribe AWS IoT Core MQTT messages](ipc-iot-core-mqtt.md).
Default: `PUB_SUB`  
`topic`  
(Optional) The topic to which the component subscribes to receive messages. If you specify `IotCore` for `type`, you can use MQTT wildcards (`+` and `#`) in this topic.

**Example: Configuration merge update (container mode)**  

```
{
  "lambdaExecutionParameters": {
    "EnvironmentVariables": {
      "DEFAULT_SNS_ARN": "arn:aws:sns:us-west-2:123456789012:mytopic"
    }
  },
  "containerMode": "GreengrassContainer"
}
```

**Example: Configuration merge update (no container mode)**  

```
{
  "lambdaExecutionParameters": {
    "EnvironmentVariables": {
      "DEFAULT_SNS_ARN": "arn:aws:sns:us-west-2:123456789012:mytopic"
    }
  },
  "containerMode": "NoContainer"
}
```

## Input data


This component accepts messages on the following topic and publishes the message as is to the target Amazon SNS topic. <a name="connector-component-local-publish"></a>By default, this component subscribes to local publish/subscribe messages. For more information about how to publish messages to this component from your custom components, see [Publish/subscribe local messages](ipc-publish-subscribe.md). 

**Default topic (local publish/subscribe):** `sns/message`

<a name="connector-component-input-properties"></a>The message accepts the following properties. Input messages must be in JSON format.

`request`  
The information about the message to send to the Amazon SNS topic.  
Type: `object` that contains the following information:    
`message`  
The content of the message as a string.  
To send a JSON object, serialize it as a string, and specify `json` for the `message_structure` property.  
Type: `string`  
`subject`  
(Optional) The subject of the message.  
Type: `string`  
The subject can be ASCII text and up to 100 characters. It must begin with a letter, number, or punctuation mark. It can't include line breaks or control characters.  
`sns_topic_arn`  
(Optional) The ARN of the Amazon SNS topic where this component publishes the message. Specify this property to override the default Amazon SNS topic.  
Type: `string`  
`message_structure`  
(Optional) The structure of the message. Specify `json` to send a JSON message that you serialize as a string in the `content` property.  
Type: `string`  
Valid values: `json`

`id`  <a name="connector-component-input-property-id"></a>
An arbitrary ID for the request. Use this property to map an input request to an output response. When you specify this property, the component sets the `id` property in the response object to this value.  
Type: `string`

**Note**  
The message size can be a maximum of 256 KB.

**Example input: String message**  

```
{
  "request": {
    "subject": "Message subject",
    "message": "Message data",
    "sns_topic_arn": "arn:aws:sns:region:account-id:topic2-name"
  },
  "id": "request123"
}
```

**Example input: JSON message**  

```
{
  "request": {
    "subject": "Message subject",
    "message": "{ \"default\": \"Message data\" }",
    "message_structure": "json"
  },
  "id": "request123"
}
```

## Output data


 <a name="connector-component-output-data"></a>This component publishes responses as output data on the following MQTT topic by default. You must specify this topic as the `subject` in the configuration for the [legacy subscription router component](legacy-subscription-router-component.md). For more information about how to subscribe to messages on this topic in your custom components, see [Publish/subscribe AWS IoT Core MQTT messages](ipc-iot-core-mqtt.md). 

**Default topic (AWS IoT Core MQTT):** `sns/message/status`

**Example output: Success**  

```
{
  "response": {
    "sns_message_id": "f80a81bc-f44c-56f2-a0f0-d5af6a727c8a",
    "status": "success"
  },
  "id": "request123"
}
```

**Example output: Failure**  

```
{
  "response" : {
    "error": "InvalidInputException",
    "error_message": "SNS Topic Arn is invalid",
    "status": "fail"
  },
  "id": "request123"
}
```

## Local log file


This component uses the following log file.

```
/greengrass/v2/logs/aws.greengrass.SNS.log
```

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` with the path to the AWS IoT Greengrass root folder.

  ```
  sudo tail -f /greengrass/v2/logs/aws.greengrass.SNS.log
  ```

## Licenses


This component includes the following third-party software/licensing:<a name="boto-3-licenses"></a>
+ [AWS SDK for Python (Boto3)](https://pypi.org/project/boto3/)/Apache License 2.0
+ [botocore](https://pypi.org/project/botocore/)/Apache License 2.0
+ [dateutil](https://pypi.org/project/python-dateutil/1.4/)/PSF License
+ [docutils](https://pypi.org/project/docutils/)/BSD License, GNU General Public License (GPL), Python Software Foundation License, Public Domain
+ [jmespath](https://pypi.org/project/jmespath/)/MIT License
+ [s3transfer](https://pypi.org/project/s3transfer/)/Apache License 2.0
+ [urllib3](https://pypi.org/project/urllib3/)/MIT License

<a name="component-core-software-license"></a>This component is released under the [Greengrass Core Software License Agreement](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf).

## Changelog


The following table describes the changes in each version of the component.


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.1.10  | Version updated for Greengrass nucleus version 2.15.0 release. | 
|  2.1.9  | Version updated for Greengrass nucleus version 2.14.0 release. | 
|  2.1.8  | Version updated for Greengrass nucleus version 2.13.0 release. | 
|  2.1.7  | Version updated for Greengrass nucleus version 2.12.0 release. | 
|  2.1.6  | Version updated for Greengrass nucleus version 2.11.0 release. | 
|  2.1.5  | Version updated for Greengrass nucleus version 2.10.0 release. | 
|  2.1.4  | Version updated for Greengrass nucleus version 2.9.0 release. | 
|  2.1.3  | Version updated for Greengrass nucleus version 2.8.0 release. | 
|  2.1.2  |  Version updated for Greengrass nucleus version 2.7.0 release.  | 
|  2.1.1  |  Version updated for Greengrass nucleus version 2.6.0 release.  | 
|  2.1.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/sns-component.html)  | 
|  2.0.8  |  Version updated for Greengrass nucleus version 2.5.0 release.  | 
|  2.0.7  |  Version updated for Greengrass nucleus version 2.4.0 release.  | 
|  2.0.6  |  Version updated for Greengrass nucleus version 2.3.0 release.  | 
|  2.0.5  |  Version updated for Greengrass nucleus version 2.2.0 release.  | 
|  2.0.4  |  Version updated for Greengrass nucleus version 2.1.0 release.  | 
|  2.0.3  |  Initial version.  | 

# Stream manager
Stream manager v2.2.1 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/public-components.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/public-components.html)

Stream manager v2.2.1 is now available. This release fixes an issue where stream manager fails to export messages to Kinesis destinations. This release also improves the performance of stream manager exports to Kinesis destinations.Stream manager v2.2.0 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/public-components.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/public-components.html)

Stream manager v2.2.0 is now available.Stream manager v2.1.13 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/public-components.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/public-components.html)

Stream manager v2.1.13 is now available. This release adds support for FIPS endpoint for AWS IoT SiteWiseStream manager v2.1.12 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/public-components.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/public-components.html)

Stream manager v2.1.12 is now available. This release changes the order that Greengrass uses to select a set of credentials for AWS service calls.Stream manager v2.1.10 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/public-components.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/public-components.html)

Stream manager v2.1.10 is now available. This release fixes an issue where the HTTPS proxy configuration doesn't trust the Greengrass CA certificate chain.Stream manager v2.1.4 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/public-components.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/public-components.html)

Stream manager v2.1.4 is now available. This release fixes an issue where entries for the same property asset with the same timestamp within a single batch return `ConflictingOperationException` from the SiteWise API which causes stream manager to continuously retry. This release also updates the default connection timeout from 3 seconds to 1 minute.Stream manager v2.1.3 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/public-components.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/public-components.html)

Stream manager v2.1.3 is now available. This release fixes a startup issue on Windows OS when running as the SYSTEM user.Stream manager v2.1.2 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/public-components.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/public-components.html)

Stream manager v2.1.2 is now available. This release fixes an issue on Windows OS that use a non-English language.Stream manager v2.1.0 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/public-components.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/public-components.html)

Stream manager v2.1.0 is now available. This release includes support for you to send telemetry metrics to Amazon EventBridge.Stream manager v2.0.12 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/public-components.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/public-components.html)

Stream manager v2.0.12 is now available. This release fixes an issue that prevented upgrades from version 2.0.7 of the stream manager component to a version between v2.0.8 and v2.0.11.

The stream manager component (`aws.greengrass.StreamManager`) enables you to process data streams to transfer to the AWS Cloud from Greengrass core devices.

For more information about how to configure and use stream manager in custom components, see [Manage data streams on Greengrass core devices](manage-data-streams.md).

**Topics**
+ [

## Versions
](#stream-manager-component-versions)
+ [

## Type
](#stream-manager-component-type)
+ [

## Operating system
](#stream-manager-component-os-support)
+ [

## Requirements
](#stream-manager-component-requirements)
+ [

## Dependencies
](#stream-manager-component-dependencies)
+ [

## Configuration
](#stream-manager-component-configuration)
+ [

## Local log file
](#stream-manager-component-log-file)
+ [

## Changelog
](#stream-manager-component-changelog)

## Versions


This component has the following versions:
+ 2.2.x
+ 2.1.x
+ 2.0.x

**Note**  <a name="stream-manager-upgrade-note"></a>
If you use stream manager to export data to the cloud, you can't upgrade version 2.0.7 of the stream manager component to a version between v2.0.8 and v2.0.11. If you are deploying stream manager for the first time, we strongly recommend that you deploy the latest version of the stream manager component.

## Type


<a name="public-component-type-generic"></a>This <a name="public-component-type-generic-phrase"></a>component is a generic component (`aws.greengrass.generic`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs the component's lifecycle scripts.

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on core devices that run the following operating systems:
+ Linux
+ Windows

## Requirements


This component has the following requirements:
+ The [token exchange role](device-service-role.md) must allow access to the AWS Cloud destinations that you use with stream manager. For more information, see:<a name="export-destinations-links"></a>
  + [AWS IoT Analytics channels](stream-export-configurations.md#export-to-iot-analytics)
  + [Amazon Kinesis data streams](stream-export-configurations.md#export-to-kinesis)
  + [AWS IoT SiteWise asset properties](stream-export-configurations.md#export-to-iot-sitewise)
  + [Amazon S3 objects](stream-export-configurations.md#export-to-s3)
+ The stream manager component is supported to run in a VPC. To deploy this component in a VPC, the following is required.
  + The stream manager component must have connectivity to the AWS service you publish data to.
    + Amazon S3: `com.amazonaws.region.s3`
    + Amazon Kinesis Data Streams: `com.amazonaws.region.kinesis-streams`
    + AWS IoT SiteWise: `com.amazonaws.region.iotsitewise.data`
  + If you publish data to Amazon S3 in the `us-east-1` region, this component will attempt to use the S3 global endpoint by default; however, this endpoint is not available through the Amazon S3 VPC interface endpoint. For more information, see [Restrictions and limitations of AWS PrivateLink for Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/privatelink-interface-endpoints.html#privatelink-limitations). To resolve this, you can choose from the following options.
    + Configure the stream manager component to use the regional S3 endpoint in the `us-east-1` region, by setting up `-Daws.s3UseUsEast1RegionalEndpoint=regional` in `JVM_ARGS`.
    + Create an Amazon S3 gateway VPC endpoint instead of an Amazon S3 interface VPC endpoint. S3 gateway endpoints support access to the S3 global endpoint. For more information, see [Create a gateway endpoint](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-s3.html#create-gateway-endpoint-s3).

### Endpoints and ports


This component must be able to perform outbound requests to the following endpoints and ports, in addition to endpoints and ports required for basic operation. For more information, see [Allow device traffic through a proxy or firewall](allow-device-traffic.md).


| Endpoint | Port | Required | Description | 
| --- | --- | --- | --- | 
|  `iotanalytics.region.amazonaws.com`  | 443 | No |  Required if you publish data to AWS IoT Analytics.  | 
|  `kinesis.region.amazonaws.com`  | 443 | No |  Required if you publish data to Firehose.  | 
|  `data.iotsitewise.region.amazonaws.com`  | 443 | No |  Required if you publish data to AWS IoT SiteWise.  | 
|  `*.s3.amazonaws.com`  | 443 | No |  Required if you publish data to S3 buckets. You can replace `*` with the name of each bucket where you publish data.  | 

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#stream-manager-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

------
#### [ 2.1.3 – 2.2.1 ]

The following table lists the dependencies for versions 2.1.3 to 2.2.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <3.0.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) |  >=0.0.0  | Hard | 

------
#### [ 2.1.11 – 2.1.12 ]

The following table lists the dependencies for version 2.1.11 to 2.1.10 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.13.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) |  >=0.0.0  | Hard | 

------
#### [ 2.1.9 – 2.1.10 ]

The following table lists the dependencies for versions 2.1.9 to 2.1.10 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.12.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) |  >=0.0.0  | Hard | 

------
#### [ 2.1.5 – 2.1.8 ]

The following table lists the dependencies for versions 2.1.5 to 2.1.8 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.11.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) |  >=0.0.0  | Hard | 

------
#### [ 2.1.2 – 2.1.4 ]

The following table lists the dependencies for versions 2.1.2 to 2.1.4 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.10.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) |  >=0.0.0  | Hard | 

------
#### [ 2.1.1 ]

The following table lists the dependencies for version 2.1.1 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.9.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) |  >=0.0.0  | Hard | 

------
#### [ 2.1.0 ]

The following table lists the dependencies for version 2.1.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.8.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) |  >=0.0.0  | Hard | 

------
#### [ 2.0.15 ]

The following table lists the dependencies for version 2.0.15 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.7.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) |  >=0.0.0  | Hard | 

------
#### [ 2.0.13 and 2.0.14 ]

The following table lists the dependencies for versions 2.0.13 and 2.0.14 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.6.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) |  >=0.0.0  | Hard | 

------
#### [ 2.0.11 and 2.0.12 ]

The following table lists the dependencies for versions 2.0.11 and 2.0.12 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.5.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) |  >=0.0.0  | Hard | 

------
#### [ 2.0.10 ]

The following table lists the dependencies for version 2.0.10 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.4.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) |  >=0.0.0  | Hard | 

------
#### [ 2.0.9 ]

The following table lists the dependencies for version 2.0.9 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.3.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) |  >=0.0.0  | Hard | 

------
#### [ 2.0.8 ]

The following table lists the dependencies for version 2.0.8 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.0 <2.2.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) |  >=0.0.0  | Hard | 

------
#### [ 2.0.7 ]

The following table lists the dependencies for version 2.0.7 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) |  >=2.0.3 <2.1.0  | Soft | 
| [Token exchange service](token-exchange-service-component.md) |  >=0.0.0  | Hard | 

------

For more information about component dependencies, see the [component recipe reference](component-recipe-reference.md#recipe-reference-component-dependencies).

## Configuration


This component provides the following configuration parameters that you can customize when you deploy the component.

`STREAM_MANAGER_STORE_ROOT_DIR`  
(Optional) The absolute path of the local directory used to store streams. This value must start with a forward slash (for example, `/data`).  
<a name="stream-manager-store-root-dir-parameter-folder-requirements"></a>You must specify an existing folder, and the [system user who runs the stream manager component](configure-greengrass-core-v2.md#configure-component-user) must have permissions to read and write to this folder. For example, you can run the following commands to create and configure a folder, `/var/greengrass/streams`, which you specify as the stream manager root folder. These commands allow the default system user, `ggc_user`, to read and write to this folder.  

```
sudo mkdir /var/greengrass/streams
sudo chown ggc_user /var/greengrass/streams
sudo chmod 700 /var/greengrass/streams
```
Default: `/greengrass/v2/work/aws.greengrass.StreamManager`

`STREAM_MANAGER_SERVER_PORT`  
(Optional) The local port number to use to communicate with stream manager.  
You can specify `0` to use a random available port.  
Default: `8088`

`STREAM_MANAGER_AUTHENTICATE_CLIENT`  
(Optional) You can make it mandatory for clients to authenticate before they can interact with stream manager. The Stream Manager SDK controls interaction between clients and stream manager. This parameter determines which clients can call the Stream Manager SDK to work with streams. For more information, see [stream manager client authentication](manage-data-streams.md#stream-manager-security-client-authentication).  
If you specify `true`, the Stream Manager SDK allows only Greengrass components as clients.  
If you specify `false`, the Stream Manager SDK allows all processes on the core device to be clients.  
Default: `true`

`STREAM_MANAGER_EXPORTER_MAX_BANDWIDTH`  
(Optional) The average maximum bandwidth (in kilobits per second) that stream manager can use to export data.  
Default: No limit

`STREAM_MANAGER_EXPORTER_THREAD_POOL_SIZE`  
(Optional) The maximum number of active threads that stream manager can use to export data.  
The optimal size depends on your hardware, stream volume, and planned number of export streams. If your export speed is slow, you can adjust this setting to find the optimal size for your hardware and business case. The CPU and memory of your core device hardware are limiting factors. To start, you might try setting this value equal to the number of processor cores on the device.  
Be careful not to set a size that's higher than your hardware can support. Each stream consumes hardware resources, so try to limit the number of export streams on constrained devices.  
Default: 5 threads

`STREAM_MANAGER_EXPORTER_S3_DESTINATION_MULTIPART_UPLOAD_MIN_PART_SIZE_BYTES`  
(Optional) The minimum size (in bytes) of a part in a multipart upload to Amazon S3. Stream manager uses this setting and the size of the input file to determine how to batch data in a multipart PUT request.  
Stream manager uses the streams `sizeThresholdForMultipartUploadBytes` property to determine whether to export to Amazon S3 as a single or multipart upload. AWS IoT Greengrass components can set this threshold when they create a stream that exports to Amazon S3.
Default: `5242880` (5 MB). This is also the minimum value.

`LOG_LEVEL`  
(Optional) The logging level for the component. Choose from the following log levels, listed here in level order:  
+ `TRACE`
+ `DEBUG`
+ `INFO`
+ `WARN`
+ `ERROR`
Default: `INFO`

`JVM_ARGS`  
(Optional) The custom Java Virtual Machine arguments to pass to stream manager at startup. Separate multiple arguments by spaces.  
Use this parameter only when you must override the default settings used by the JVM. For example, you might need to increase the default heap size if you plan to export a large number of streams.

`startupTimeoutSeconds`  
(Optional) The maximum of time in seconds for the component to start. The component's state changes to `ERRORED` if it exceeds this timeout.  
Default: `120`

**Example: Configuration merge update**  
The following example configuration specifies to use a non-default port.  

```
{
  "STREAM_MANAGER_SERVER_PORT": "18088"
}
```

## Local log file


This component uses the following log file.

------
#### [ Linux ]

```
/greengrass/v2/logs/aws.greengrass.StreamManager.log
```

------
#### [ Windows ]

```
C:\greengrass\v2\logs\aws.greengrass.StreamManager.log
```

------

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the path to the AWS IoT Greengrass root folder.

------
#### [ Linux ]

  ```
  sudo tail -f /greengrass/v2/logs/aws.greengrass.StreamManager.log
  ```

------
#### [ Windows (PowerShell) ]

  ```
  Get-Content C:\greengrass\v2\logs\aws.greengrass.StreamManager.log -Tail 10 -Wait
  ```

------

## Changelog


The following table describes the changes in each version of the component.


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.2.1  | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/stream-manager-component.html) | 
|  2.2.0  | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/stream-manager-component.html) | 
|  2.1.13  | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/stream-manager-component.html) | 
|  2.1.12  | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/stream-manager-component.html) | 
|  2.1.11  | Version updated for Greengrass nucleus version 2.12.0 release. | 
|  2.1.10  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/stream-manager-component.html)  | 
|  2.1.9  | Version updated for Greengrass nucleus version 2.11.0 release. | 
|  2.1.8  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/stream-manager-component.html)  | 
|  2.1.7  |  <a name="changelog-stream-manager-2.1.7"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/stream-manager-component.html)  | 
|  2.1.6  |  <a name="changelog-stream-manager-2.1.6"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/stream-manager-component.html)  | 
|  2.1.5  | Version updated for Greengrass nucleus version 2.10.0 release. | 
|  2.1.4  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/stream-manager-component.html)  | 
|  2.1.3  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/stream-manager-component.html)  | 
|  2.1.2  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/stream-manager-component.html)  | 
|  2.1.1  | Version updated for Greengrass nucleus version 2.8.0 release. | 
|  2.1.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/stream-manager-component.html)  | 
|  2.0.15  |  Version updated for Greengrass nucleus version 2.6.0 release.  | 
|  2.0.14  |  This version contains bug fixes and improvements.  | 
|  2.0.13  |  Version updated for Greengrass nucleus version 2.5.0 release.  | 
| 2.0.12 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/stream-manager-component.html)  | 
|  2.0.11  |  Version updated for Greengrass nucleus version 2.4.0 release.  | 
|  2.0.10  |  Version updated for Greengrass nucleus version 2.3.0 release.  | 
|  2.0.9  |  Version updated for Greengrass nucleus version 2.2.0 release.  | 
|  2.0.8  |  Version updated for Greengrass nucleus version 2.1.0 release.  | 
|  2.0.7  |  Initial version.  | 

# System log forwarder
System log forwarder v2.1.0 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/system-log-forwarder-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/system-log-forwarder-component.html)

System log forwarder v2.1.0 is available.System log forwarder v2.0.1 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/system-log-forwarder-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/system-log-forwarder-component.html)

System log forwarder v2.0.1 is available. This version updates the component recipe to properly support aarch64 (arm64) systems.System log forwarder v2.0.0 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/system-log-forwarder-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/system-log-forwarder-component.html)

System log forwarder component v2.0.0 is available. Initial version released.

The System log forwarder (`aws.greengrass.SystemLogForwarder`) uploads active system logs directly to Amazon CloudWatch using the CloudWatch HTTPS API.

**Important**  
This component will only forward systemd-journald logs generated during runtime. For more information on systemd-journald logs, see [systemd-journald](https://www.freedesktop.org/software/systemd/man/latest/systemd-journald.service.html) and [journalctl](https://www.freedesktop.org/software/systemd/man/latest/journalctl.html#).

**Note**  
This component requires specific permissions to create and manage CloudWatch log groups and streams.

**Topics**
+ [

## Versions
](#system-log-forwarder-component-versions)
+ [

## Type
](#system-log-forwarder-component-type)
+ [

## Operating system
](#system-log-forwarder-component-os-support)
+ [

## Requirements
](#system-log-forwarder-component-requirements)
+ [

## Endpoints and ports
](#system-log-forwarder-component-endpoints)
+ [

## Dependencies
](#system-log-forwarder-component-dependencies)
+ [

## Configuration
](#system-log-forwarder-component-configuration)
+ [

## Changelog
](#system-log-forwarder-component-changelog)

## Versions


This component has the following versions:
+ 2.1.x
+ 2.0.x

## Type


<a name="public-component-type-generic"></a>This <a name="public-component-type-generic-phrase"></a>component is a generic component (`aws.greengrass.generic`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs the component's lifecycle scripts.

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component must be installed on systemd-based Linux systems.

## Requirements


This component has the following requirements:

The component requires access to create log and stream groups in CloudWatch as well as permission to perform the PutLogEvents HTTP call. You must, at minimum, add the following policy permissions to your Greengrass device's role alias:

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
    {
      "Effect": "Allow",
      "Action": ["logs:CreateLogGroup"],
      "Resource": "arn:aws:logs:us-east-1:111122223333:log-group:greengrass/systemLogs:*"
    },
    {
      "Effect": "Allow",
      "Action": ["logs:CreateLogStream", "logs:PutLogEvents"],
      "Resource": "arn:aws:logs:us-east-1:111122223333:log-group:greengrass/systemLogs:log-stream:${credentials-iot:ThingName}"
    }
  ]
}
```

------

**Note**  
For more information, see the System Log Forwarder [Github](https://github.com/aws-greengrass/aws-greengrass-system-log-forwarder) page.

## Endpoints and ports


This component must be able to perform outbound requests to the following endpoints and ports, in addition to endpoints and ports required for basic operation. For more information, see [Allow device traffic through a proxy or firewall](allow-device-traffic.md).


| Endpoint | Port | Required | Description | 
| --- | --- | --- | --- | 
|  `logs.region.amazonaws.com`  | 443 | No |  Required if you write logs to CloudWatch Logs.  | 

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#system-log-forwarder-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

------
#### [ 2.1.x ]

The following table lists the dependencies for version 2.1.x of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Token exchange service](token-exchange-service-component.md) | >=2.0.0 | Hard | 
| [Greengrass nucleus lite](greengrass-nucleus-lite-component.md) | >=2.3.0 | Soft | 

------
#### [ 2.0.x ]

The following table lists the dependencies for version 2.0.x of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Token exchange service](token-exchange-service-component.md) | >=2.0.0 | Hard | 

------

## Configuration


This component provides the following configuration parameters that you can customize when you deploy the component.

------
#### [ 2.0.x-2.1.x ]

`maxUploadIntervalSec`  
The maximum period at which system log forwarder will attempt to upload logs. Since log forwarder will upload logs when the memory fills, it may still upload more often than the configured maximum cadence.

`maxRetriesCount`  
Number of times system log forwarder will attempt to retry a transient HTTP error.

`bufferCapacity`  
The size of the ring buffer for in-memory log storage.

`logGroup`  
The log path in CloudWatch.

`logStream`  
The CloudWatch logStream.

`filters`  
A map of filter configurations for the core device.    
`services`  
A list of service name filters that System Log Forwarder will use to determine which logs gets uploaded. A log will only be uploaded if the service it originated from matches at least one of the filters in this list. The filters in this list may either be a string that the service name must fully match, or a string ending with \$1, which means the prefix must match.  
Default: `[ggl.*]`  
A log will only be uploaded if the service it originated from matches at least one of the filters in this list.
Using the value \$1 will include all available services.

**Example configuration:**  
The example below will filter logs by all services included in Greengrass Nucleus Lite.  

```
{
    "maxUploadIntervalSec": 300,
    "maxRetriesCount": 3,
    "bufferCapacity": 1048576,
    "logGroup": "greengrass/systemLogs",
    "logStream": "deviceName",
    "filters": {
        "services": ["ggl.*"]
    }
}
```

------

## Changelog


The following table describes the changes in each version of the component.


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.1.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/system-log-forwarder-component.html)  | 
|  2.0.1  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/system-log-forwarder-component.html)  | 
|  2.0.0  |  Initial version.  | 

# Systems Manager Agent


The AWS Systems Manager Agent component (`aws.greengrass.SystemsManagerAgent`) installs the Systems Manager Agent, so you can manage core devices with Systems Manager. Systems Manager is an AWS service that you can use to view and control your infrastructure on AWS, including Amazon EC2 instances, on-premises servers and virtual machines (VMs), and edge devices. Systems Manager enables you to view operational data, automate operation tasks, and maintain security and compliance. For more information, see [What is AWS Systems Manager?](https://docs.aws.amazon.com/systems-manager/latest/userguide/what-is-systems-manager.html) and [About Systems Manager Agent](https://docs.aws.amazon.com/systems-manager/latest/userguide/prereqs-ssm-agent.html) in the *AWS Systems Manager User Guide*.

<a name="about-systems-manager-capabilities"></a>Systems Manager tools and features are called *capabilities*. Greengrass core devices support all Systems Manager capabilities. For more information about these capabilities and how to use Systems Manager to manage core devices, see [Systems Manager capabilities](https://docs.aws.amazon.com/systems-manager/latest/userguide/features.html) in the *AWS Systems Manager User Guide*.

**Topics**
+ [

## Versions
](#systems-manager-agent-component-versions)
+ [

## Type
](#systems-manager-agent-component-type)
+ [

## Operating system
](#systems-manager-agent-component-os-support)
+ [

## Requirements
](#systems-manager-agent-component-requirements)
+ [

## Dependencies
](#systems-manager-agent-component-dependencies)
+ [

## Configuration
](#systems-manager-agent-component-configuration)
+ [

## Local log file
](#systems-manager-agent-component-log-file)
+ [

## See also
](#systems-manager-agent-component-see-also)
+ [

## Changelog
](#systems-manager-agent-component-changelog)

## Versions


This component has the following versions:
+ 1.3.x
+ 1.2.x
+ 1.1.x
+ 1.0.x

## Type


<a name="public-component-type-generic"></a>This <a name="public-component-type-generic-phrase"></a>component is a generic component (`aws.greengrass.generic`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs the component's lifecycle scripts.

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on Linux core devices only.

## Requirements


This component has the following requirements:
+ A Greengrass core device that runs on a 64-bit Linux platform: Armv8 (AArch64) or x86\$164.
+ You must have an AWS Identity and Access Management (IAM) service role that Systems Manager can assume. This role must include the [AmazonSSMManagedInstanceCore](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore) managed policy or a custom policy that defines equivalent permissions. For more information, see [Create an IAM service role for edge devices](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-setting-up-edge-devices.html#systems-manager-setting-up-edge-devices-service-role) in the *AWS Systems Manager User Guide*.

  When you deploy this component, you must specify this role's name for the `SSMRegistrationRole` configuration parameter.
+ The [Greengrass device role](device-service-role.md) must allow the `ssm:AddTagsToResource` and `ssm:RegisterManagedInstance` actions. The device role must also allow the `iam:PassRole` action for the IAM service role that fulfills the previous requirement. The following example IAM policy grants these permissions.

  ```
  {
    "Version": "2012-10-17",		 	 	 
    "Statement": [
      {
        "Action": [
          "iam:PassRole"
        ],
        "Effect": "Allow",
        "Resource": [
          "arn:aws:iam::account-id:role/SSMServiceRole"
        ]
      },
      {
        "Action": [
          "ssm:AddTagsToResource",
          "ssm:RegisterManagedInstance"
        ],
        "Effect": "Allow",
        "Resource": "*"
      }
    ]
  }
  ```

### Endpoints and ports


This component must be able to perform outbound requests to the following endpoints and ports, in addition to endpoints and ports required for basic operation. For more information, see [Allow device traffic through a proxy or firewall](allow-device-traffic.md).


| Endpoint | Port | Required | Description | 
| --- | --- | --- | --- | 
|  `ec2messages.region.amazonaws.com`  | 443 | Yes |  Communicate with the Systems Manager service in the AWS Cloud.  | 
|  `ssm.region.amazonaws.com`  | 443 | Yes |  Register the core device as a Systems Manager managed node.  | 
|  `ssmmessages.region.amazonaws.com`  | 443 | Yes |  Communicate with Session Manager, a capability of Systems Manager, in the AWS Cloud.  | 

For more information, see [Reference: ec2messages, ssmmessages, and other API calls](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-setting-up-messageAPIs.html) in the *AWS Systems Manager User Guide*.

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#systems-manager-agent-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

The following table lists the dependencies for versions 1.0.0 to 1.3.0 of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Token exchange service](token-exchange-service-component.md) |  >=2.0.0 <3.0.0 | Hard | 

For more information about component dependencies, see the [component recipe reference](component-recipe-reference.md#recipe-reference-component-dependencies).

## Configuration


This component provides the following configuration parameters that you can customize when you deploy the component.

`SSMRegistrationRole`  
The IAM service role that Systems Manager can assume and that includes the [AmazonSSMManagedInstanceCore](https://console.aws.amazon.com/iam/home#/policies/arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore) managed policy or a custom policy that defines equivalent permissions. For more information, see [Create an IAM service role for edge devices](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-setting-up-edge-devices-service-role.html) in the *AWS Systems Manager User Guide*.

`SSMOverrideExistingRegistration`  
(Optional) If the core device already runs the Systems Manager Agent registered with a hybrid activation, you can override the device's existing Systems Manager Agent registration. Set this option to `true` to register the core device as a managed node using the Systems Manager Agent that this component provides.  
This option applies only to devices that are registered with a hybrid activation. If the core device runs on an Amazon EC2 instance with the Systems Manager Agent installed and an instance profile role configured, the Amazon EC2 instance's existing managed node ID starts with `i-`. When you install the Systems Manager Agent component, the Systems Manager agent registers a new managed node whose ID starts with `mi-` instead of `i-`. Then, you can use the managed node whose ID starts with `mi-` to manage the core device with Systems Manager.
Default: `false`

`SSMResourceTags`  
(Optional) The tags to add to the Systems Manager managed node that this component creates for the core device. You can use these tags to manage groups of core devices with Systems Manager. For example, you can run a command on all devices that have a tag that you specify.  
Specify a list where each tag is an object with a `Key` and a `Value`. For example, the following value for `SSMResourceTags` instructs this component to set the **Owner** tag to **richard-roe** on the core device's managed node.  

```
[
  {
    "Key": "Owner",
    "Value": "richard-roe"
  }
]
```
This component ignores these tags if the managed node already exists and `SSMOverrideExistingRegistration` is `false`.

**Example: Configuration merge update**  
The following example configuration specifies to use a service role named `SSMServiceRole` to allow the core device to register and communicate with Systems Manager.  

```
{
  "SSMRegistrationRole": "SSMServiceRole",
  "SSMOverrideExistingRegistration": false,
  "SSMResourceTags": [
    {
      "Key": "Owner",
      "Value": "richard-roe"
    },
    {
      "Key": "Team",
      "Value": "solar"
    }
  ]
}
```

## Local log file


The Systems Manager Agent software writes logs to a folder outside the Greengrass root folder. For more information, see [Viewing Systems Manager Agent logs](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-agent-logs.html) in the *AWS Systems Manager User Guide*.

The Systems Manager Agent component uses shell scripts to install, start, and stop the Systems Manager Agent. You can find the output from these scripts in the following log file.

```
/greengrass/v2/logs/aws.greengrass.SystemsManagerAgent.log
```

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` with the path to the AWS IoT Greengrass root folder.

  ```
  sudo tail -f /greengrass/v2/logs/aws.greengrass.SystemsManagerAgent.log
  ```

## See also

+ [Manage Greengrass core devices with AWS Systems Manager](manage-with-systems-manager.md)
+ [What is AWS Systems Manager?](https://docs.aws.amazon.com/systems-manager/latest/userguide/what-is-systems-manager.html) in the *AWS Systems Manager User Guide*
+ [About Systems Manager Agent](https://docs.aws.amazon.com/systems-manager/latest/userguide/prereqs-ssm-agent.html) in the *AWS Systems Manager User Guide*

## Changelog


The following table describes the changes in each version of the component.


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  1.3.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/systems-manager-agent-component.html)  | 
|  1.2.4  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/systems-manager-agent-component.html)  | 
|  1.2.3  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/systems-manager-agent-component.html)  | 
|  1.1.0  |  This version contains bug fixes and improvements.  | 
|  1.0.0  |  Initial version.  | 

# Token exchange service


The token exchange service component (`aws.greengrass.TokenExchangeService`) provides AWS credentials that you can use to interact with AWS services in your custom components.

The token exchange service runs as a local server. This local server connects to the AWS IoT credentials provider using the AWS IoT role alias that you configure in the [Greengrass core nucleus component](greengrass-nucleus-component.md). The component provides two environment variables, `AWS_CONTAINER_CREDENTIALS_FULL_URI` and `AWS_CONTAINER_AUTHORIZATION_TOKEN`. `AWS_CONTAINER_CREDENTIALS_FULL_URI` defines the URI to this local server. When a component creates an AWS SDK client, the client recognizes this URI environment variable and uses the token in the `AWS_CONTAINER_AUTHORIZATION_TOKEN` to connect to the token exchange service and retrieve AWS credentials. This allows Greengrass core devices to call AWS service operations. For more information about how to use this component in custom components, see [Interact with AWS services](interact-with-aws-services.md).

**Important**  <a name="token-exchange-service-aws-sdk-requirement"></a>
Support to acquire AWS credentials in this way was added to the AWS SDKs on July 13th, 2016. Your component must use an AWS SDK version that was created on or after that date. For more information, see [Using a supported AWS SDK](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html#task-iam-roles-minimum-sdk) in the *Amazon Elastic Container Service Developer Guide*.

**Note**  
Components using the AWS Default Credential Chain may discover and use other sources of credentials, if they exist. Within the Amazon Amazon Elastic Container Service (Amazon ECS) container credentials `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` will take precedence over `AWS_CONTAINER_CREDENTIALS_FULL_URI`, meaning that token exchange service credentials may not work within Amazon Elastic Container Service (Amazon ECS). For more, see [standardized credential providers](https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html) 

**Topics**
+ [

## Versions
](#token-exchange-service-component-versions)
+ [

## Type
](#token-exchange-service-component-type)
+ [

## Operating system
](#token-exchange-service-component-os-support)
+ [

## Dependencies
](#token-exchange-service-component-dependencies)
+ [

## Configuration
](#token-exchange-service-component-configuration)
+ [

## Local log file
](#token-exchange-service-component-log-file)
+ [

## Changelog
](#token-exchange-service-component-changelog)

## Versions


This component has the following versions:
+ 2.0.x

## Type


<a name="public-component-type-generic"></a>This <a name="public-component-type-generic-phrase"></a>component is a generic component (`aws.greengrass.generic`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs the component's lifecycle scripts.

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on core devices that run the following operating systems:
+ Linux
+ Windows

## Dependencies


This component doesn't have any dependencies.

## Configuration


This component provides the following configuration parameters that you can customize when you deploy the component.

`port`  
The port to use for token exchange service connections. The token exchange service will restart after port configuration changes.

`credentialRetryInSec`  
Specifies retry intervals in seconds when Token Exchange Service encounters credential request errors.    
`clientError`  
The retry interval in seconds for client errors (4xx HTTP status codes).  
Default: `120`  
Valid values: `10` to `42900`  
`serverError`  
The retry interval in seconds for server errors (5xx HTTP status codes).  
Default: `60`  
Valid values: `10` to `42900`  
`unknownError`  
The retry interval in seconds for unknown errors (connection errors and HTTP status codes outside the 4xx and 5xx ranges).  
Default: `300`  
Valid values: `10` to `42900`

**Example: Configuration merge update**  

```
{
   "port": 2020,
   "credentialRetryInSec": {
    "clientError": 30,
    "serverError": 45,
    "unknownError": 60
   }
}
```

## Local log file


This component uses the same log file as the [Greengrass nucleus](greengrass-nucleus-component.md) component.

------
#### [ Linux ]

```
/greengrass/v2/logs/greengrass.log
```

------
#### [ Windows ]

```
C:\greengrass\v2\logs\greengrass.log
```

------

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the path to the AWS IoT Greengrass root folder.

------
#### [ Linux ]

  ```
  sudo tail -f /greengrass/v2/logs/greengrass.log
  ```

------
#### [ Windows (PowerShell) ]

  ```
  Get-Content C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
  ```

------

## Changelog


The following table describes the changes in each version of the component.


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.0.3  |  Initial version.  | 

# IoT SiteWise OPC UA collector


The IoT SiteWise OPC UA collector component (`aws.iot.SiteWiseEdgeCollectorOpcua`) enables AWS IoT SiteWise gateways to collect data from local OPC UA servers.

With this component, AWS IoT SiteWise gateways can connect to multiple OPC UA servers. For more information about AWS IoT SiteWise gateways, see [Using AWS IoT SiteWise at the edge](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/gateways-ggv2.html) in the *AWS IoT SiteWise User Guide*.

**Topics**
+ [

## Versions
](#iotsitewise-opcua-collector-component-versions)
+ [

## Type
](#iotsitewise-opcua-collector-component-type)
+ [

## Operating system
](#iotsitewise-opcua-collector-component-os-support)
+ [

## Requirements
](#iotsitewise-opcua-collector-component-requirements)
+ [

## Dependencies
](#iotsitewise-opcua-collector-component-dependencies)
+ [

## Configuration
](#iotsitewise-opcua-collector-component-configuration)
+ [

## Input data
](#iotsitewise-opcua-collector-component-input-data)
+ [

## Output data
](#iotsitewise-opcua-collector-component-output-data)
+ [

## Local log file
](#iotsitewise-opcua-collector-component-log-file)
+ [

## Licenses
](#iotsitewise-opcua-collector-component-licenses)
+ [

## Changelog
](#iotsitewise-opcua-collector-component-changelog)
+ [

## See also
](#iotsitewise-opcua-collector-component-see-also)

## Versions


This component has the following versions:
+ 3.1.x
+ 3.0.x
+ 2.6.x
+ 2.5.x
+ 2.4.x
+ 2.3.x
+ 2.2.x
+ 2.1.x
+ 2.0.x

## Type


<a name="public-component-type-generic"></a>This <a name="public-component-type-generic-phrase"></a>component is a generic component (`aws.greengrass.generic`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs the component's lifecycle scripts.

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on core devices that run the following operating systems:
+ Linux
+ Windows

## Requirements


This component has the following requirements:
+ The Greengrass core device must run on one of the following platforms:
  + os: Ubuntu 20.04 or later

    architecture: x86\$164 (AMD64) or ARMv8 (Aarch64)
  + os: Red Hat Enterprise Linux (RHEL) 8

    architecture: x86\$164 (AMD64) or ARMv8 (Aarch64)
  + os: Amazon Linux 2

    architecture: x86\$164 (AMD64) or ARMv8 (Aarch64)
  + os: Debian 11

    architecture: x86\$164 (AMD64) or ARMv8 (Aarch64)
  + os: Windows Server 2019 or later

    architecture: x86\$164 (AMD64)
+ The Greengrass core device must allow outbound network connectivity to OPC UA servers.

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#iotsitewise-opcua-collector-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

The following table lists the dependencies for all versions of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.3.0 <3.0.0 | Hard | 
| [Stream manager](stream-manager-component.md) | >2.0.10<3.0.0 | Hard | 
| [Secret manager](secret-manager-component.md) | >=2.0.8 <3.0.0 | Hard | 

For more information about component dependencies, see the [component recipe reference](component-recipe-reference.md#recipe-reference-component-dependencies).

## Configuration


This component doesn't have any configuration parameters.

You can use the AWS IoT SiteWise console or API to configure the IoT SiteWise OPC UA collector component. For more information, see [Step 4: Add data sources - optional](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/create-gateway-ggv2.html#add-data-sources-console) in the *AWS IoT SiteWise User Guide*.

## Input data


This component only accepts data in the following formats, all others will be ignored and discarded. The table below maps the OPC UA data types to their SiteWise equivalent.


|  **SiteWise data type**  |  **OPC UA data type**  |  **Description**  | 
| --- | --- | --- | 
|  `STRING`  |  `String` `Guid` `XmlElement`  |  A string of maximum length 1024 bytes.  | 
|  `INTEGER`  |  `SByte` `Byte` `Int16` `UInt16` `Int32` `UInt32`\$1 `Int64`\$1  |  A signed 32-bit integer with a range from `-2,147,483,648 to 2,147,483,647` .  | 
|  `DOUBLE`  |  `UInt32`\$1 `Int64`\$1 `Float` `Double`  |  A floating point number with range from `–10^100 to 10^100` and `IEEE 754` double precision.  | 
|  `BOOLEAN`  |  `Boolean`  |  `true` or `false`.  | 

\$1 For OPC UA data types `UInt32` and `Int64`, its SiteWise data type will be `INTEGER` if SiteWise is able to represent its value, otherwise it will be `DOUBLE`.

## Output data




This component writes `BatchPutAssetPropertyValue` messages to AWS IoT Greengrass stream manager. For more information, see [BatchPutAssetPropertyValue](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_BatchPutAssetPropertyValue.html) in the *AWS IoT SiteWise API Reference*.

## Local log file


This component uses the following log file.

------
#### [ Linux ]

```
/greengrass/v2/logs/aws.iot.SiteWiseEdgeCollectorOpcua.log
```

------
#### [ Windows ]

```
C:\greengrass\v2\logs\aws.iot.SiteWiseEdgeCollectorOpcua.log
```

------

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the path to the AWS IoT Greengrass root folder.

------
#### [ Linux ]

  ```
  sudo tail -f /greengrass/v2/logs/aws.iot.SiteWiseEdgeCollectorOpcua.log
  ```

------
#### [ Windows (PowerShell) ]

  ```
  Get-Content C:\greengrass\v2\logs\aws.iot.SiteWiseEdgeCollectorOpcua.log -Tail 10 -Wait
  ```

------

## Licenses


<a name="component-core-software-license"></a>This component is released under the [Greengrass Core Software License Agreement](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf).

## Changelog


The following table describes the changes in each version of the component.


|  **Version**  |  **Changes**  | 
| --- | --- | 
| 3.1.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-opcua-collector-component.html)  | 
| 3.0.3 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-opcua-collector-component.html)  | 
| 3.0.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-opcua-collector-component.html)  | 
| 3.0.1 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-opcua-collector-component.html)  | 
| 3.0.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-opcua-collector-component.html)  | 
| 2.6.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-opcua-collector-component.html)  | 
| 2.5.1 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-opcua-collector-component.html)  | 
| 2.5.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-opcua-collector-component.html)  | 
|  2.4.2  | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-opcua-collector-component.html) | 
|  2.4.1  | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-opcua-collector-component.html) | 
|  2.4.0  | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-opcua-collector-component.html)  | 
|  2.3.0  | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-opcua-collector-component.html) | 
|  2.2.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-opcua-collector-component.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-opcua-collector-component.html)  | 
|  2.1.3  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-opcua-collector-component.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-opcua-collector-component.html)  | 
|  2.1.1  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-opcua-collector-component.html)  | 
|  2.0.3  |  Bug fixes and improvements.  | 
|  2.0.2  |  Bug fixes and improvements to asset priority syncing with edge.  | 
|  2.0.1  |  Initial version.  | 

## See also

+ [What is AWS IoT SiteWise?](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/what-is-sitewise.html) in the *AWS IoT SiteWise User Guide*.

# IoT SiteWise OPC UA data source simulator


The IoT SiteWise OPC UA data source simulator component (`aws.iot.SiteWiseEdgeOpcuaDataSourceSimulator`) starts a local OPC UA server that generates sample data. Use this OPC UA server to simulate a data source read by the [IoT SiteWise OPC UA collector component](iotsitewise-opcua-collector-component.md) on an AWS IoT SiteWise gateway. Then, you can explore AWS IoT SiteWise features using this sample data. For more information about AWS IoT SiteWise gateways, see [Using AWS IoT SiteWise at the edge](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/gateways-ggv2.html) in the *AWS IoT SiteWise User Guide*.

**Topics**
+ [

## Versions
](#iotsitewise-opcua-data-source-simulator-component-versions)
+ [

## Type
](#iotsitewise-opcua-data-source-simulator-component-type)
+ [

## Operating system
](#iotsitewise-opcua-data-source-simulator-component-os-support)
+ [

## Requirements
](#iotsitewise-opcua-data-source-simulator-component-requirements)
+ [

## Dependencies
](#iotsitewise-opcua-data-source-simulator-component-dependencies)
+ [

## Configuration
](#iotsitewise-opcua-data-source-simulator-component-configuration)
+ [

## Local log file
](#iotsitewise-opcua-data-source-simulator-component-log-file)
+ [

## Changelog
](#iotsitewise-opcua-data-source-simulator-component-changelog)
+ [

## See also
](#iotsitewise-opcua-data-source-simulator-component-see-also)

## Versions


This component has the following versions:
+ 1.0.x

## Type


<a name="public-component-type-generic"></a>This <a name="public-component-type-generic-phrase"></a>component is a generic component (`aws.greengrass.generic`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs the component's lifecycle scripts.

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on core devices that run the following operating systems:
+ Linux
+ Windows

## Requirements


This component has the following requirements:
+ The Greengrass core device must be able to use port 4840 on the local host. This component's local OPC UA server runs at this port.

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#iotsitewise-opcua-data-source-simulator-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

The following table lists the dependencies for all versions of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.3.0 <3.0.0 | Hard | 

For more information about component dependencies, see the [component recipe reference](component-recipe-reference.md#recipe-reference-component-dependencies).

## Configuration


This component doesn't have any configuration parameters.

## Local log file


This component uses the following log file.

------
#### [ Linux ]

```
/greengrass/v2/logs/aws.iot.SiteWiseEdgeOpcuaDataSourceSimulator.log
```

------
#### [ Windows ]

```
C:\greengrass\v2\logs\aws.iot.SiteWiseEdgeOpcuaDataSourceSimulator.log
```

------

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the path to the AWS IoT Greengrass root folder.

------
#### [ Linux ]

  ```
  sudo tail -f /greengrass/v2/logs/aws.iot.SiteWiseEdgeOpcuaDataSourceSimulator.log
  ```

------
#### [ Windows (PowerShell) ]

  ```
  Get-Content C:\greengrass\v2\logs\aws.iot.SiteWiseEdgeOpcuaDataSourceSimulator.log -Tail 10 -Wait
  ```

------

## Changelog


The following table describes the changes in each version of the component.


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  1.0.0  |  Initial version. Adds support for Windows Server 2016 or higher.  | 

## See also

+ [What is AWS IoT SiteWise?](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/what-is-sitewise.html) in the *AWS IoT SiteWise User Guide*.

# IoT SiteWise publisher
IoT SiteWise publisher v2.2.0 released[https://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-publisher-component.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-publisher-component.html)

IoT SiteWise publisher component v2.2.0 is available. This release updates the component to compress data before sending it to the AWS IoT SiteWise service, which reduces bandwidth usage by up to 75 percent.

The IoT SiteWise publisher component (`aws.iot.SiteWiseEdgePublisher`) enables AWS IoT SiteWise gateways to export data from the edge to the AWS Cloud.

For more information about AWS IoT SiteWise gateways, see [Using AWS IoT SiteWise at the edge](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/gateways-ggv2.html) in the *AWS IoT SiteWise User Guide*.

**Topics**
+ [

## Versions
](#iotsitewise-publisher-component-versions)
+ [

## Type
](#iotsitewise-publisher-component-type)
+ [

## Operating system
](#iotsitewise-publisher-component-os-support)
+ [

## Requirements
](#iotsitewise-publisher-component-requirements)
+ [

## Dependencies
](#iotsitewise-publisher-component-dependencies)
+ [

## Configuration
](#iotsitewise-publisher-component-configuration)
+ [

## Input data
](#iotsitewise-publisher-component-input-data)
+ [

## Local log file
](#iotsitewise-publisher-component-log-file)
+ [

## Troubleshooting and debugging
](#iotsitewise-publisher-component-debug)
+ [

## Licenses
](#iotsitewise-publisher-component-licenses)
+ [

## Changelog
](#iotsitewise-publisher-component-changelog)
+ [

## See also
](#iotsitewise-publisher-component-see-also)

## Versions


This component has the following versions:
+ 4.1.x
+ 4.0.x
+ 3.2.x
+ 3.1.x
+ 3.0.x
+ 2.4.x
+ 2.3.x
+ 2.2.x
+ 2.1.x
+ 2.0.x

## Type


<a name="public-component-type-generic"></a>This <a name="public-component-type-generic-phrase"></a>component is a generic component (`aws.greengrass.generic`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs the component's lifecycle scripts.

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on core devices that run the following operating systems:
+ Linux
+ Windows

## Requirements


This component has the following requirements:
+ The Greengrass core device must run on one of the following platforms:
  + os: Ubuntu 18.04 or later

    architecture: x86\$164 (AMD64) or ARMv8 (Aarch64)
  + os: Red Hat Enterprise Linux (RHEL) 8

    architecture: x86\$164 (AMD64) or ARMv8 (Aarch64)
  + os: Amazon Linux 2

    architecture: x86\$164 (AMD64) or ARMv8 (Aarch64)
  + os: Debian 11

    architecture: x86\$164 (AMD64) or ARMv8 (Aarch64)
  + os: Windows Server 2019 or later

    architecture: x86\$164 (AMD64)
+ The Greengrass core device must connect to the Internet.
+ The Greengrass core device must be authorized to perform the `iotsitewise:BatchPutAssetPropertyValue` action. For more information, see [Authorize core devices to interact with AWS services](https://docs.aws.amazon.com/greengrass/v2/developerguide/device-service-role.html).  
**Example permissions policy**  

------
#### [ JSON ]

****  

  ```
  {
      "Version":"2012-10-17",		 	 	 
      "Statement": [
          {
              "Effect": "Allow",
              "Action": "iotsitewise:BatchPutAssetPropertyValue",
              "Resource": "*"
          }
      ]
  }
  ```

------

### Endpoints and ports


This component must be able to perform outbound requests to the following endpoints and ports, in addition to endpoints and ports required for basic operation. For more information, see [Allow device traffic through a proxy or firewall](allow-device-traffic.md).


| Endpoint | Port | Required | Description | 
| --- | --- | --- | --- | 
|  `data.iotsitewise.region.amazonaws.com`  | 443 | Yes |  Publish data to AWS IoT SiteWise.  | 

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#iotsitewise-publisher-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

The following table lists the dependencies for versions 2.0.x to 2.2.x of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Greengrass nucleus](greengrass-nucleus-component.md) | >=2.3.0<3.0.0 | Hard | 
| [Stream manager](stream-manager-component.md) | >=2.0.10<3.0.0 | Hard | 

For more information about component dependencies, see the [component recipe reference](component-recipe-reference.md#recipe-reference-component-dependencies).

## Configuration


This component doesn't have any configuration parameters.

You can use the AWS IoT SiteWise console or API to configure the IoT SiteWise publisher component. For more information, see [Step 3: Configure publisher - optional](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/create-gateway-ggv2.html#configure-publisher) in the *AWS IoT SiteWise User Guide*.

## Input data




This component reads `PutAssetPropertyValueEntry` messages from AWS IoT Greengrass stream manager. For more information, see [PutAssetPropertyValueEntry](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_PutAssetPropertyValueEntry.html) in the *AWS IoT SiteWise API Reference*.

## Local log file


This component uses the following log file.

------
#### [ Linux ]

```
/greengrass/v2/logs/aws.iot.SiteWiseEdgePublisher.log
```

------
#### [ Windows ]

```
C:\greengrass\v2\logs\aws.iot.SiteWiseEdgePublisher.log
```

------

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the path to the AWS IoT Greengrass root folder.

------
#### [ Linux ]

  ```
  sudo tail -f /greengrass/v2/logs/aws.iot.SiteWiseEdgePublisher.log
  ```

------
#### [ Windows (PowerShell) ]

  ```
  Get-Content C:\greengrass\v2\logs\aws.iot.SiteWiseEdgePublisher.log -Tail 10 -Wait
  ```

------

## Troubleshooting and debugging


This component includes a new events log to help customers identify and fix problems. The log file is separate from the local log file, and is found in the following location. Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the path to the AWS IoT Greengrass root folder.

------
#### [ Linux ]

```
/greengrass/v2/work/aws.iot.SiteWiseEdgePublisher/logs/IotSiteWisePublisherEvents.log
```

------
#### [ Windows ]

```
C:\greengrass\v2\work\aws.iot.SiteWiseEdgePublisher\logs\IotSiteWisePublisherEvents.log
```

------

This log includes detailed information and troubleshooting instructions. Troubleshooting information is provided alongside the diagnostics, with a description of how to remedy the issue, and sometimes with links to further information. Diagnostic information includes the following:
+ Severity level
+ Timestamp
+ Additional event-specific information

**Example log**  

```
accountBeingThrottled:
  Summary: Data upload speed slowed due to quota limits
  Level: WARN
  Timestamp: '2023-06-09T21:30:24.654Z'
  Description: The IoT SiteWise Publisher is limited to the "Rate of data points ingested"
    quota for a customers account. See the associated documentation and associated
    metric for the number of requests that were limited for more information. Note
    that this may be temporary and not require any change, although if the issue continues
    you may need to request an increase for the mentioned quota.
  FurtherInformation:
  - https://docs.aws.amazon.com/iot-sitewise/latest/userguide/quotas.html
  - https://docs.aws.amazon.com/iot-sitewise/latest/userguide/troubleshooting-gateway.html#gateway-issue-data-streams
  AssociatedMetrics:
  - Name: TotalErrorCount
    Description: The total number of errors of this type that occurred.
    Value: 327724.0
  AssociatedData:
  - Name: AggregatePropertyAliases
    Description: The aggregated property aliases of the throttled data.
    FileLocation: /greengrass/v2/work/aws.iot.SiteWiseEdgePublisher/./logs/data/AggregatePropertyAliases_1686346224654.log
```

## Licenses


<a name="component-core-software-license"></a>This component is released under the [Greengrass Core Software License Agreement](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf).

## Changelog


The following table describes the changes in each version of the component.


|  **Version**  |  **Changes**  | 
| --- | --- | 
| 4.1.4 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-publisher-component.html)  | 
| 4.1.3 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-publisher-component.html)  | 
| 4.1.2 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-publisher-component.html)  | 
| 4.1.1 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-publisher-component.html)  | 
| 4.1.0 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-publisher-component.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-publisher-component.html)  | 
|  4.0.3  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-publisher-component.html)  | 
|  4.0.2  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-publisher-component.html)  | 
|  4.0.1  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-publisher-component.html)  | 
|  4.0.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-publisher-component.html)  | 
|  3.2.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-publisher-component.html)  | 
|  3.1.4  |   Version 3.1.4 was discontinued on February 20, 2025. The improvements in this version are available in later versions of this component.  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-publisher-component.html)  | 
|  3.1.3  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-publisher-component.html)  | 
|  3.1.2  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-publisher-component.html)  | 
|  3.1.1  |   Version 3.1.1 was discontinued on March 12, 2024. The improvements in this version are available in later versions of this component.  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-publisher-component.html)  | 
|  3.1.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-publisher-component.html)  | 
|  3.0.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-publisher-component.html)  | 
|  2.4.1  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-publisher-component.html)  | 
|  2.4.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-publisher-component.html)  | 
|  2.3.3  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-publisher-component.html)  | 
|  2.3.2  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-publisher-component.html)  | 
|  2.3.1  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-publisher-component.html)  | 
|  2.2.3  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-publisher-component.html)  | 
|  2.2.2  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-publisher-component.html)  | 
|  2.2.1  |   This version doesn't support HTTP proxy configuration. Version 2.2.2 and higher reintroduces support for this feature.  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-publisher-component.html)  | 
|  2.2.0  |   This version doesn't support HTTP proxy configuration. Version 2.2.2 and higher reintroduces support for this feature.  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-publisher-component.html)  | 
|  2.1.4  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-publisher-component.html)  | 
|  2.1.3  |   This version is no longer available, except in the US East (Ohio), Canada (Central), and AWS GovCloud (US-East) Regions. This component version requires Java version 11 or greater to run. The improvements in this version are available in later versions of this component.  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-publisher-component.html)  | 
|  2.1.2  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-publisher-component.html)  | 
|  2.1.1  |  Bug fixes and improvements.  | 
|  2.1.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-publisher-component.html)  | 
|  2.0.2  |  Bug fixes and improvements.  | 
|  2.0.1  |  Initial version.  | 

## See also

+ [What is AWS IoT SiteWise?](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/what-is-sitewise.html) in the *AWS IoT SiteWise User Guide*.

# IoT SiteWise processor


The IoT SiteWise processor component (`aws.iot.SiteWiseEdgeProcessor`) enables AWS IoT SiteWise Classic streams, V2 gateways to process data at the edge.

With this component, AWS IoT SiteWise gateways can use asset models and assets to process data on gateway devices. For more information about AWS IoT SiteWise gateways, see [Using AWS IoT SiteWise at the edge](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/gateways-ggv2.html) in the *AWS IoT SiteWise User Guide*.

**Note**  
The data processing pack (DPP) feature will no longer be open to new customers starting November 7, 2025. If you would like to use DPP, sign up prior to that date. Existing customers can continue to use the service as normal. For more information, see [Data processing pack availability change](https://docs.aws.amazon.com/iot-sitewise/latest/appguide/iotsitewise-dpp-availability-change.html) in the *AWS IoT SiteWise User Guide*.

**Topics**
+ [

## Versions
](#iotsitewise-processor-component-versions)
+ [

## Type
](#iotsitewise-processor-component-type)
+ [

## Operating system
](#iotsitewise-processor-component-os-support)
+ [

## Requirements
](#iotsitewise-processor-component-requirements)
+ [

## Dependencies
](#iotsitewise-processor-component-dependencies)
+ [

## Configuration
](#iotsitewise-processor-component-configuration)
+ [

## Local log file
](#iotsitewise-processor-component-log-file)
+ [

## Licenses
](#iotsitewise-processor-component-licenses)
+ [

## Changelog
](#iotsitewise-processor-component-changelog)
+ [

## See also
](#iotsitewise-processor-component-see-also)

## Versions


This component has the following versions:
+ 3.5.x
+ 3.4.x
+ 3.3.x
+ 3.2.x
+ 3.1.x
+ 3.0.x
+ 2.2.x
+ 2.1.x
+ 2.0.x

## Type


<a name="public-component-type-generic"></a>This <a name="public-component-type-generic-phrase"></a>component is a generic component (`aws.greengrass.generic`). The [Greengrass nucleus](greengrass-nucleus-component.md) runs the component's lifecycle scripts.

<a name="public-component-type-more-information"></a>For more information, see [Component types](develop-greengrass-components.md#component-types).

## Operating system


This component can be installed on core devices that run the following operating systems:
+ Linux
+ Windows

## Requirements


This component has the following requirements:
+ The Greengrass core device must run on one of the following platforms:
  + os: Ubuntu 20.04 or later

    architecture: x86\$164 (AMD64)
  + os: Red Hat Enterprise Linux (RHEL) 8

    architecture: x86\$164 (AMD64)
  + os: Amazon Linux 2

    architecture: x86\$164 (AMD64)
  + os: Windows Server 2019 or later

    architecture: x86\$164 (AMD64)
  + os: Debian 11 (Bullseye) or later

    architecture: x86\$164 (AMD64)
+ The Greengrass core device must allow inbound traffic on port 443.
+ The Greengrass core device must allow outbound traffic on port 443 and 8883.
+ The following ports are reserved for use by AWS IoT SiteWise: 80, 443, 3001, 4569, 4572, 8000, 8081, 8082, 8084, 8085, 8086, 8445, 9000, 9500, 11080, and 50010. Using a reserved port for traffic can result in a terminated connection.
**Note**  
Port 8087 is required only for version 2.0.15 and later of this component.
+ The [Greengrass device role](https://docs.aws.amazon.com/greengrass/v2/developerguide/device-service-role.html) must have permissions that allow you to use AWS IoT SiteWise gateways on your AWS IoT Greengrass V2 devices. For more information, see [Requirements](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/configure-gateway-ggv2.html#gateway-requirements) in the *AWS IoT SiteWise User Guide*.

### Endpoints and ports


This component must be able to perform outbound requests to the following endpoints and ports, in addition to endpoints and ports required for basic operation. For more information, see [Allow device traffic through a proxy or firewall](allow-device-traffic.md).


| Endpoint | Port | Required | Description | 
| --- | --- | --- | --- | 
|  `model.iotsitewise.region.amazonaws.com`  | 443 | Yes |  Get information about your AWS IoT SiteWise assets and asset models.  | 
|  `edge.iotsitewise.region.amazonaws.com`  | 443 | Yes |  Get information about the core device's AWS IoT SiteWise gateway configuration.  | 
|  `ecr.region.amazonaws.com`  | 443 | Yes |  Download AWS IoT SiteWise Edge gateway Docker images from Amazon Elastic Container Registry.  | 
|  `iot.region.amazonaws.com`  | 443 | Yes |  Get device endpoints for your AWS account.  | 
|  `sts.region.amazonaws.com`  | 443 | Yes |  Get the ID of your AWS account.  | 
|  `monitor.iotsitewise.region.amazonaws.com`  | 443 | No |  Required if you access AWS IoT SiteWise Monitor portals on the core device.  | 

## Dependencies


When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the [released versions](#iotsitewise-processor-component-changelog) of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the [AWS IoT Greengrass console](https://console.aws.amazon.com//greengrass). On the component details page, look for the **Dependencies** list.

The following table lists the dependencies for versions 2.0.x to 2.1.x of this component.


| Dependency | Compatible versions | Dependency type | 
| --- | --- | --- | 
| [Token exchange service](token-exchange-service-component.md) | >=2.0.3 <3.0.0 | Hard | 
| [Stream manager](stream-manager-component.md) | >=2.0.10 <3.0.0 | Hard | 
| [Greengrass CLI](greengrass-cli-component.md) | >=2.3.0 <3.0.0 | Hard | 

For more information about component dependencies, see the [component recipe reference](component-recipe-reference.md#recipe-reference-component-dependencies).

## Configuration


This component doesn't have any configuration parameters.

## Local log file


This component uses the following log file.

------
#### [ Linux ]

```
/greengrass/v2/logs/aws.iot.SiteWiseEdgeProcessor.log
```

------
#### [ Windows ]

```
C:\greengrass\v2\logs\aws.iot.SiteWiseEdgeProcessor.log
```

------

**To view this component's logs**
+ Run the following command on the core device to view this component's log file in real time. Replace `/greengrass/v2` or *C:\$1greengrass\$1v2* with the path to the AWS IoT Greengrass root folder.

------
#### [ Linux ]

  ```
  sudo tail -f /greengrass/v2/logs/aws.iot.SiteWiseEdgeProcessor.log
  ```

------
#### [ Windows (PowerShell) ]

  ```
  Get-Content C:\greengrass\v2\logs\aws.iot.SiteWiseEdgeProcessor.log -Tail 10 -Wait
  ```

------

## Licenses


This component includes the following third-party software/licensing:

### Third-party Licenses

+ Apache-2.0
+ MIT
+ BSD-2-Clause
+ BSD-3-Clause
+ CDDL-1.0
+ CDDL-1.1
+ ISC
+ Zlib
+ GPL-3.0-with-GCC-exception
+ Public Domain
+ Python-2.0
+ Unicode-DFS-2015
+ BSD-1-Clause
+ OpenSSL
+ EPL-1.0
+ EPL-2.0
+ GPL-2.0-with-classpath-exception
+ MPL-2.0
+ CC0-1.0
+ JSON

<a name="component-core-software-license"></a>This component is released under the [Greengrass Core Software License Agreement](https://greengrass-release-license.s3.us-west-2.amazonaws.com/greengrass-license-v1.pdf).

## Changelog


The following table describes the changes in each version of the component.


|  **Version**  |  **Changes**  | 
| --- | --- | 
| 3.5.1 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-processor-component.html)  | 
| 3.4.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-processor-component.html)  | 
| 3.3.1 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-processor-component.html)  | 
| 3.3.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-processor-component.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-processor-component.html) | 
|  3.2.1  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-processor-component.html)  | 
|  3.2.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-processor-component.html)  | 
|  3.1.3  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-processor-component.html)  | 
|  3.1.1  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-processor-component.html)  | 
|  3.1.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-processor-component.html)  | 
|  3.0.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-processor-component.html)  | 
| 2.2.1 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-processor-component.html)  | 
| 2.1.37 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-processor-component.html)  | 
| 2.1.35 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-processor-component.html)  | 
| 2.1.34 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-processor-component.html)  | 
| 2.1.33 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-processor-component.html)  | 
| 2.1.32 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-processor-component.html)  | 
| 2.1.31 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-processor-component.html)  | 
| 2.1.29 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-processor-component.html)  | 
| 2.1.28 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-processor-component.html)  | 
| 2.1.24 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-processor-component.html)  | 
| 2.1.23 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-processor-component.html)  | 
|  2.1.21  |   Upgrading from 2.0.x to 2.1.x will result in loss of local data.  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-processor-component.html)  | 
|  2.0.16  |  This version contains bug fixes and improvements.  | 
|  2.0.15  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-processor-component.html)  | 
|  2.0.14  |  This version contains bug fixes and improvements.  | 
|  2.0.13  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-processor-component.html)  | 
|  2.0.9  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-processor-component.html)  | 
|  2.0.7  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-processor-component.html)  | 
|  2.0.6  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-processor-component.html)  | 
|  2.0.5  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-processor-component.html)  | 
|  2.0.2  |  Initial version.  | 

## See also

+ [What is AWS IoT SiteWise?](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/what-is-sitewise.html) in the *AWS IoT SiteWise User Guide*.

# Publisher-supported components



|  | 
| --- |
| Publisher-supported components are in a preview release for AWS IoT Greengrass and are subject to change. These components are not supported by AWS. You must contact the Publisher for any issues with each of the components. | 

The Greengrass Publisher-supported components are developed, offered, and serviced by third-party component vendors. Third-party component vendors are either from the AWS Partner Device Catalog, AWS Heroes, or community vendors. You can purchase the components in this catalog by contacting the third-party component vendor directly.

The Greengrass Publisher-supported components include the following:

**Topics**
+ [

## AIShield.Edge
](#publisher-supported-components-AIShield.Edge)
+ [

## AI EdgeLabs Sensor
](#publisher-supported-components-AIEdgeLabs)
+ [

## Greengrass S3 Ingestor
](#publisher-supported-components-S3Ingestor)

## AIShield.Edge


This component was developed and is supported by AIShield, powered by Bosch. Boost your AI security with AIShield.Edge. This component is designed to seamlessly deploy threat-informed, tailored defenses to edge devices, which safeguardes your devices against AI attacks.

This component offers the following benefits:
+ Seamlessly transition from vulnerability analysis with AIShield AI Security to fortified edge defenses within AWS
+ Deploy tailored defenses across multiple edge devices with ease
+ Broad protection tailored to diverse AI setups which supports various model types and frameworks
+ Stay updated with seamless integration into Amazon SageMaker AI and Greengrass workflows
+ Gain immediate insights into potential threats, with data relayed directly to AWS IoT Core
+ A cohesive AI security pathway for defense deployment on the edge from AIShield AI Security on the AWS Marketplace

This component must run on the following platform:
+ os: linux

If you are interested in purchasing this component, contact Bosch Software and Digital Solutions: AIShield.Contact@bosch.com.

## AI EdgeLabs Sensor


This component was developed and is supported by AI EdgeLabs. AI EdgeLabs Sensor is a container-based application that contains AI-based threat detection and prevention capabilities. AI Sensor is wrapped into a Greengrass component and deployed as a standalone container on the core device alongside other Greengrass components.

This current component is a container-based agent that continuously verifies network communication, looks for threat patterns in software running on the Edge Host or IoT gateway. This component uses eBPF, behavioral verification of processes bandwidth, and the host-based configuration. The main functionality of this component is based on NDR/IPS and EDR functions.

This component offers the following benefits:
+ AI-based threat detection against network attacks and malware (EDR/NDR)
+ Automated AI-based Incident response (IPS)
+ Host-local threat intelligence with minimal data-transfer outside
+ Lightweight deployment with Docker and Greengrass

This component must run on one of the following platforms:
+ os: linux

If you are interested in purchasing this component, contact AI EdgeLabs: contact@edgelabs.ai.

## Greengrass S3 Ingestor


This component was developed and is supported by Nathan Glover. The Greengrass S3 Ingestor component is designed to be used with the [stream manager component](https://docs.aws.amazon.com/greengrass/v2/developerguide/stream-manager-component.html). This component takes a line-delimited stream of JSON messages from stream manager and batches them into a GZIP file. This component enables efficient ingestion of data into Amazon S3 for further processing or for storage. This component doesn’t support sending data to the AWS Cloud in realtime.

This component must run on one of the following platforms:
+ os: linux
+ os: Windows

If you are interested in purchasing this component, contact Nathan Glover: nathan@glovers.id.au.

# Community components


The Greengrass Software Catalog is an index of Greengrass components that are developed by the Greengrass community. From this catalog, you can download, modify, and deploy components to create your Greengrass applications. You can view the catalog at the following link: [https://github.com/aws-greengrass/aws-greengrass-software-catalog](https://github.com/aws-greengrass/aws-greengrass-software-catalog).

Each component has a public GitHub repository that you can explore. View the Greengrass Software Catalog on GitHub to find the full list of community components. For example, this catalog includes the following components:
+ **[Amazon Kinesis Video Streams](https://github.com/awslabs/aws-greengrass-labs-kvs-stream-uploader)**

  This component ingests audio and video streams from local cameras that use [Real Time Streaming Protocol (RTSP)](https://en.wikipedia.org/wiki/Real_Time_Streaming_Protocol). The component then uploads the audio and video streams to [Amazon Kinesis Video Streams](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/what-is-kinesis-video.html).
+ **[Bluetooth IoT gateway](https://github.com/awslabs/aws-greengrass-labs-bluetooth-gateway)**

  This component uses the [BluePy](https://ianharvey.github.io/bluepy-doc/index.html) library that enables communication with Bluetooth Low Energy (LE) devices to create Bluetooth LE client interfaces.
+ **[Certificate Rotator](https://github.com/awslabs/aws-greengrass-labs-certificate-rotator)**

  This component provides a means of rotating the AWS IoT Greengrass core device certificate and private key, across your fleet, at scale.
+ **[Containerized secure tunneling](https://github.com/awslabs/aws-greengrass-labs-containerized-secure-tunneling)**

  This component provides a Docker container for secure tunneling with all dependencies and matching libraries in a reusable recipe that doesn't rely on a specific host operating system.
+ **[Grafana](https://github.com/awslabs/aws-greengrass-labs-dashboard-grafana)**

  This component enables you to host a [Grafana](https://grafana.com/) server on a Greengrass core device. You can use Grafana dashboards to visualize and manage data on the core device.
+ **[GStreamer for Amazon Lookout for Vision](https://github.com/awslabs/aws-greengrass-labs-lookoutvision-gstreamer)**

  This component provides a GStreamer plugin so that you can perform Lookout for Vision anomaly detection in your custom GStreamer pipelines.
+ **[Home assistant](https://github.com/awslabs/aws-greengrass-labs-component-for-home-assistant)**

  This component enables the customer to use [Home Assistant](https://www.home-assistant.io/) to provide local control of smart home devices. It provides integration with AWS services at the edge and in the cloud to deliver home automation solutions that extend Home Assistant.
+ **[InfluxDBGrafana dashboard](https://github.com/awslabs/aws-greengrass-labs-dashboard-influxdb-grafana)**

  This component provides a one-click experience to set up the InfluxDB and Grafana components. It connects InfluxDB to Grafana and automates the setup of a local Grafana dashboard that renders AWS IoT Greengrass telemetry in real time.
+ **[InfluxDB](https://github.com/awslabs/aws-greengrass-labs-database-influxdb)**

  This component provides an [InfluxDB](https://www.influxdata.com/products/influxdb/) time-series database on a Greengrass core device. You can use this component to process data from IoT sensors, analyze data in real time, and monitor operations at the edge.
+ **[InfluxDB publisher](https://github.com/awslabs/aws-greengrass-labs-telemetry-influxdbpublisher)**

  This component relays AWS IoT Greengrass system health telemetry from the [Nucleus emitter plugin](https://github.com/aws-greengrass/aws-greengrass-telemetry-nucleus-emitter) to InfluxDB. This component can also forward custom telemetry to InfluxDB.
+ **[IoT pubsub framework](https://github.com/aws-samples/aws-greengrass-application-framework)**

  This framework provides an application architecture, template code, and deployable examples that help improve code quality for distributed event-driven IoT pubsub applications using AWS IoT Greengrass v2 custom components. For more information, see [Create AWS IoT Greengrass components](create-components.md).
+ **[Jupyter Labs](https://github.com/awslabs/aws-greengrass-labs-jupyterlab)**

  This component deploys JupyterLab to an AWS IoT Greengrass core device. The Jupyter environment has access to the process and environment variable resources set by AWS IoT Greengrass, simplifying the process of testing and developing components written in Python.
+ **[Local web server](https://github.com/awslabs/aws-greengrass-labs-local-web-server)**

  This component enables you to create a local web user interface on a Greengrass core device. You can create a local web user interface that enables you to configure device and application settings or monitor the device, for example.
+ **[LoRaWaN protocol adapter](https://github.com/awslabs/aws-greengrass-labs-component-for-the-things-stack-lorawan)**

  This component ingests data from local wireless devices that use the LoRaWaN protocol, which is a low-power wide-area network (LPWAN) protocol. The component enables you to analyze and act on data locally without communicating with the cloud.
+ **[ Modbus TCP](https://github.com/awslabs/aws-greengrass-labs-modbus-tcp-protocol-adapter)**

  This component collects data from local devices using the ModbusTCP protocol and publishes it to selected data streams.
+ **[Node-RED](https://github.com/awslabs/aws-greengrass-labs-nodered)**

  This component installs Node-RED on an AWS IoT Greengrass core device using NPM. The component depends on the [Node-RED Auth](https://github.com/awslabs/aws-greengrass-labs-nodered-auth) component which must be explicitly deployed and configured. You can use the [Node-RED CLI for Greengrass](https://github.com/awslabs/aws-greengrass-labs-node-red-app-cli) to deploy Node-RED flows to AWS IoT Greengrass devices.
+ **[Node-RED Docker](https://github.com/awslabs/aws-greengrass-labs-nodered-docker)**

  This component installs Node-RED on the AWS IoT Greengrass core device using the official Node-RED Docker container. The component depends on the [Node-RED Auth](https://github.com/awslabs/aws-greengrass-labs-nodered-auth) component which must be explicitly deployed and configured. You can use the [Node-RED CLI for Greengrass](https://github.com/awslabs/aws-greengrass-labs-node-red-app-cli) to deploy Node-RED flows to AWS IoT Greengrass devices.
+ **[Node-RED Auth](https://github.com/awslabs/aws-greengrass-labs-nodered-auth)**

  This component configures a user name and password to secure the Node-RED instance running on an AWS IoT Greengrass core device.
+ **[OpenThread Border Router](https://github.com/awslabs/aws-greengrass-labs-openthread-border-router)**

  This component deploys the OpenThread Border Router Docker container. The component helps to compose a Matter device that includes a Thread border router.
+ **[OSI Pi Streaming Data Connector](https://github.com/awslabs/aws-greengrass-labs-osi-pi-streaming-data-connector)**

  This component provides streaming real-time data ingestion from OSI Pi Data Archive to a modern data architecture on AWS. It integrates to OSI Pi Asset Framework that is centrally managed over AWS IoT PubSub messaging.
+ **[Parsec Provider](https://github.com/awslabs/aws-greengrass-labs-parsec-provider)**

  This component enables AWS IoT Greengrass devices to integrate hardware security solutions using the open source [Parsec](https://parsec.community/) project from [Cloud Native Computing Foundation (CNCF)](https://www.cncf.io/).
+ **[PostgreSQL DB](https://github.com/awslabs/aws-greengrass-labs-database-postgresql)**

  This component provides support for [PostgreSQL](https://www.postgresql.org/) relational database at the edge. Customers can use this component to provision and manage a local PostgreSQL instance inside a docker container.
+ **[S3 file uploader](https://github.com/awslabs/aws-greengrass-labs-s3-file-uploader)**

  This component monitors a directory for new files, uploads them to Amazon Simple Storage Service (Amazon S3), and then deletes them after a successful upload.
+ **[Secrets Manager client](https://github.com/awslabs/aws-greengrass-labs-secretsmanagerclient)**

  This component provides a CLI tool that can be used by other components needing to retrieve secrets from the Secrets Manager component in a recipe lifecycle script.
+ **[TES routing to container](https://github.com/awslabs/aws-greengrass-labs-tes-router)**

  This component configures nftables or iptables on an AWS IoT Greengrass device so that it can use the [Token exchange service](token-exchange-service-component.md) component with containers.
+ **[WebRTC](https://github.com/awslabs/aws-greengrass-labs-webrtc)**

  This component ingests audio and video streams from RTSP cameras connected to the AWS IoT Greengrass core device. And then the component turns the audio and video streams into peer-to-peer communication or relay through Amazon Kinesis Video Streams.

To request a feature or report a bug, open a GitHub issue on the repository for that component. AWS doesn't provide support for community components. For more information, see the **CONTRIBUTING.md** file in each component's repository.

Several AWS-provided components are also open source. For more information, see [Open source AWS IoT Greengrass Core software](open-source.md).

# AWS IoT Greengrass development tools
Greengrass development tools

Use AWS IoT Greengrass development tools to create, test, build, publish, and deploy custom Greengrass components.
+ **[Greengrass Development Kit CLI](greengrass-development-kit-cli.md)**

  Use the AWS IoT Greengrass Development Kit Command-Line Interface (GDK CLI) in your local development environment to create components from templates and community components in the [Greengrass Software Catalog](greengrass-software-catalog.md). You can use the GDK CLI to build the component and publish the component to the AWS IoT Greengrass service as a private component in your AWS account.
+ **[Greengrass Command Line Interface](gg-cli.md)**

  Use the Greengrass Command Line Interface (Greengrass CLI) on Greengrass core devices to deploy and debug Greengrass components. The Greengrass CLI is a component that you can deploy to your core devices to create local deployments, view details about installed components, and explore log files.
+ **[Local debug console](local-debug-console-component.md)**

  Use the local debug console on Greengrass core devices to deploy and debug Greengrass components using a local dashboard web interface. The local debug console is a component that you can deploy to your core devices to create local deployments and view details about installed components.

AWS IoT Greengrass also provides the following SDKs that you can use in custom Greengrass components:
+ The AWS IoT Device SDK and the AWS IoT Greengrass Component SDK, which contain the interprocess communication (IPC) library. For more information, see [Use the AWS IoT Device SDK to communicate with the Greengrass nucleus, other components, and AWS IoT CoreCommunicate with the Greengrass nucleus, other components, and AWS IoT Core](interprocess-communication.md).
+ The Stream Manager SDK, which you can use to transfer data streams to the AWS Cloud. For more information, see [Manage data streams on Greengrass core devices](manage-data-streams.md).

**Topics**
+ [

# AWS IoT Greengrass Development Kit Command-Line Interface
](greengrass-development-kit-cli.md)
+ [

# Greengrass Command Line Interface
](gg-cli.md)
+ [

# Use AWS IoT Greengrass Testing Framework
](gg-testing-framework.md)

# AWS IoT Greengrass Development Kit Command-Line Interface
Greengrass Development Kit CLIGreengrass Development Kit CLI v1.6.2[https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html)

Version 1.6.2 of the Greengrass Development Kit CLI is available. This version fixes an issue where Windows gradlew.bat does not work due to the relative path. This version also contains additional improvements.Greengrass Development Kit CLI v1.6.1[https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html)

Version 1.6.1 of the Greengrass Development Kit CLI is available. This version contains bug fixes and improvements.Greengrass Development Kit CLI v1.6.0[https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html)

Version 1.6.0 of the Greengrass Development Kit CLI is available. This version adds a recipe validation check against the Greengrass recipe schema during the `component build` and `component publish` commands. This update helps developers to identify actionable issues within their component recipes earlier in the component creation process. This version also adds a confidence test suite to the template that can be pulled down by the `test-e2e init` command. This confidence test suite includes eight generic tests that can be used and extended to fit basic component testing needs.Greengrass Development Kit CLI v1.5.0[https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html)

Version 1.5.0 of the Greengrass Development Kit CLI is available. This version updates the patterns recognized by the `excludes` build option when `build_system` is `zip`. This version will now recognize glob patterns which match pathnames based on their wildcard characters. This enables custom specification of which directories to exclude from.Greengrass Development Kit CLI v1.4.0[https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html)

Version 1.4.0 of the Greengrass Development Kit CLI is available. This version adds a new `config` command that starts an interactive prompt to modify fields within an existing GDK configuration file. This version also modifies the `gdk component build` and `gdk component publish` commands to verify that the recipe size is within Greengrass requirements (<=16000 bytes) before proceeding.Greengrass Development Kit CLI v1.3.0[https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html)

Version 1.3.0 of the Greengrass Development Kit CLI is available. This version adds a new `test-e2e` command to support end-to-end testing of components using Open Test Framework.Greengrass Development Kit CLI v1.2.3[https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html)

Version 1.2.3 of the Greengrass Development Kit CLI is available. This version contains bug fixes.Greengrass Development Kit CLI v1.2.2[https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html)

Version 1.2.2 of the Greengrass Development Kit CLI is available. This version contains improvements and bug fixes.Greengrass Development Kit CLI v1.1.0[https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html)

Version 1.1.0 of the Greengrass Development Kit CLI is available. This version adds new arguments to the `component init` and `component publish` commands. This version also updates the `component publish` command to build the component if it isn't built.

The AWS IoT Greengrass Development Kit Command-Line Interface (GDK CLI) provides features that help you develop [custom Greengrass components](develop-greengrass-components.md). You can use the GDK CLI to create, build, and publish custom components. When you create a component repository with the GDK CLI, you can start from a template or a community component from the [Greengrass Software Catalog](greengrass-software-catalog.md). Then, you can choose a build system that packages files as ZIP archives, uses a Maven or Gradle build script, or runs a custom build command. After you create a component, you can use the GDK CLI to publish it to the AWS IoT Greengrass service, so you can use the AWS IoT Greengrass console or API to deploy the component to your Greengrass core devices.

When you develop Greengrass components without the GDK CLI, you must update the version and artifact URIs in the [component recipe file](component-recipe-reference.md) each time you create a new version of the component. When you use the GDK CLI, it can automatically update the version and artifact URIs for you each time you publish a new version of the component.

The GDK CLI is open source and available on GitHub. You can customize and extend the GDK CLI to meet your component development needs. We invite you to open issues and pull requests on the GitHub repository. You can find the GDK CLI source at the following link: [https://github.com/aws-greengrass/aws-greengrass-gdk-cli](https://github.com/aws-greengrass/aws-greengrass-gdk-cli).

## Prerequisites


To install and use the Greengrass Development Kit CLI, you need the following:
+ An AWS account. If you don't have one, see [Set up an AWS account](setting-up.md#set-up-aws-account).
+ A Windows, macOS, or Unix-like development computer with an internet connection.
+ For GDK CLI version 1.1.0 or later, [Python](https://www.python.org/downloads/) 3.6 or later installed on your development computer.

  For GDK CLI version 1.0.0, [Python](https://www.python.org/downloads/) 3.8 or later installed on your development computer.
+ [Git](https://git-scm.com/) installed on your development computer.
+ <a name="development-component-aws-cli-prerequisite"></a>AWS Command Line Interface (AWS CLI) installed and configured with credentials on your development computer. For more information, see [Installing, updating, and uninstalling the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) and [Configuring the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html) in the *AWS Command Line Interface User Guide*.
**Note**  
If you use a Raspberry Pi or another 32-bit ARM device, install AWS CLI V1. AWS CLI V2 isn't available for 32-bit ARM devices. For more information, see [Installing, updating, and uninstalling the AWS CLI version 1](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv1.html).
+ To use the GDK CLI to publish components to the AWS IoT Greengrass service, you must have the following permissions:
  + `s3:CreateBucket`
  + `s3:GetBucketLocation`
  + `s3:PutObject`
  + `greengrass:CreateComponentVersion`
  + `greengrass:ListComponentVersions`
+ To use the GDK CLI to build a component whose artifacts exist in an S3 bucket and not in the local file system, you must have the following permissions:
  + `s3:ListBucket`

  This feature is available for GDK CLI v1.1.0 and later.

## Changelog


The following table describes the changes in each version of the GDK CLI. For more information, see the [GDK CLI Releases page](https://github.com/aws-greengrass/aws-greengrass-gdk-cli/releases) on GitHub.


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  1.6.2  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html)  | 
|  1.6.1  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html)  | 
| 1.6.0 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html)  | 
|  1.5.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html)  | 
| 1.4.0 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html)  | 
| 1.3.0 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html)  | 
| 1.2.3 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html)  | 
| 1.2.2 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html)  | 
| 1.2.1 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html)  | 
| 1.2.0 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html)  | 
|  1.1.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html)  | 
|  1.0.0  |  Initial version.  | 

# Install or update the AWS IoT Greengrass Development Kit Command-Line Interface
Install or update the Greengrass Development Kit CLI

The AWS IoT Greengrass Development Kit Command-Line Interface (GDK CLI) is built on Python, so you can use `pip` to install it on your development computer.

**Tip**  
You can also install the GDK CLI in a Python virtual environments such as [venv](https://docs.python.org/3/library/venv.html#module-venv). For more information, see [Virtual Environments and Packages](https://docs.python.org/3/tutorial/venv.html) in the *Python 3 documentation*.

**To install or update the GDK CLI**

1. Run the following command to install the latest version of the GDK CLI from its [GitHub repository](https://github.com/aws-greengrass/aws-greengrass-gdk-cli).

   ```
   python3 -m pip install -U git+https://github.com/aws-greengrass/aws-greengrass-gdk-cli.git@v1.6.2
   ```
**Note**  
To install a specific version of the GDK CLI, replace *versionTag* with the version tag to install. You can view version tags for the GDK CLI in its [GitHub repository](https://github.com/aws-greengrass/aws-greengrass-gdk-cli/tags).  

   ```
   python3 -m pip install -U git+https://github.com/aws-greengrass/aws-greengrass-gdk-cli.git@versionTag
   ```

1. <a name="gdk-cli-verify-installation"></a>Run the following command to verify that the GDK CLI installed successfully.

   ```
   gdk --help
   ```

   If the `gdk` command isn't found, add its folder to PATH.
   + On Linux devices, add `/home/MyUser/.local/bin` to PATH, and replace *MyUser* with the name of your user.
   + On Windows devices, add `PythonPath\\Scripts` to PATH, and replace *PythonPath* with the path to the Python folder on your device.

You can now use the GDK CLI to create, build, and publish Greengrass components. For more information about how to use the GDK CLI, see [AWS IoT Greengrass Development Kit Command-Line Interface commands](greengrass-development-kit-cli-commands.md).

# AWS IoT Greengrass Development Kit Command-Line Interface commands
GDK CLI commands

The AWS IoT Greengrass Development Kit Command-Line Interface (GDK CLI) provides a command line interface that you can use to create, build, and publish Greengrass components on your development computer. GDK CLI commands use the following format.

```
gdk <command> <subcommand> [arguments]
```

When you [install the GDK CLI](install-greengrass-development-kit-cli.md), the installer adds `gdk` to the PATH so you can run the GDK CLI from the command line.

You can use the following arguments with any command:
+ Use `-h` or `--help` for information about a GDK CLI command.
+ Use `-v` or `--version` to see what version of GDK CLI is installed.
+ Use `-d` or `--debug` to output verbose logs that you can use to debug the GDK CLI.

This section describes the GDK CLI commands and provides examples for each command. The synopsis for each command shows its arguments and their usage. Optional arguments are shown in square brackets.

**Topics**
+ [

# component
](greengrass-development-kit-cli-component.md)
+ [

# config
](greengrass-development-kit-cli-config.md)
+ [

# test-e2e
](greengrass-development-kit-cli-test.md)

# component


Use the `component` command in the AWS IoT Greengrass Development Kit Command-Line Interface (GDK CLI) to create, build, and publish custom Greengrass components.

**Topics**
+ [

## init
](#greengrass-development-kit-cli-component-init)
+ [

## build
](#greengrass-development-kit-cli-component-build)
+ [

## publish
](#greengrass-development-kit-cli-component-publish)
+ [

## list
](#greengrass-development-kit-cli-component-list)

## init


Initialize a Greengrass component folder from a component template or community component.

<a name="gdk-cli-component-templates-community-components"></a>The GDK CLI retrieves community components from the [Greengrass Software Catalog](greengrass-software-catalog.md) and component templates from the [AWS IoT Greengrass Component Templates repository on GitHub](https://github.com/aws-greengrass/aws-greengrass-component-templates).

**Note**  
<a name="gdk-cli-component-init-empty-folder-requirement"></a>If you use GDK CLI v1.0.0, you must run this command in an empty folder. The GDK CLI downloads the template or community component to the current folder.  
<a name="gdk-cli-component-init-empty-folder-requirement-gdk-cli-v1.1.0"></a>If you use GDK CLI v1.1.0 or later, you can specify the `--name` argument to specify the folder where the GDK CLI downloads the template or community component. If you use this argument, specify a folder that doesn't exist. The GDK CLI creates the folder for you. If you don't specify this argument, the GDK CLI uses the current folder, which must be empty.  
If the component uses the [zip build system](gdk-cli-configuration-file.md#gdk-cli-configuration-file-build-system), the GDK CLI zips certain files in the component's folder into a zip file with the same name as the component folder. For example, if the component folder's name is `HelloWorld`, the GDK CLI creates a zip file named `HelloWorld.zip`. In the component recipe, the zip artifact name must match the name of the component folder. If you use GDK CLI version 1.0.0 on a Windows device, the component folder and zip file names must contain only lowercase letters.  
If you initialize a template or community component that uses the zip build system to a folder with a different name than the template or component, you must change the zip artifact name in the component recipe. Update the `Artifacts` and `Lifecycle` definitions such that the zip file name matches the name of the component folder. The following example highlights the zip file name in the `Artifacts` and `Lifecycle` definitions.  

```
{
  ...
  "Manifests": [
    {
      "Platform": {
        "os": "all"
      },
      "Artifacts": [
        {
          "URI": "s3://BUCKET_NAME/COMPONENT_NAME/COMPONENT_VERSION/HelloWorld.zip",
          "Unarchive": "ZIP"
        }
      ],
      "Lifecycle": {
        "Run": "python3 -u {artifacts:decompressedPath}/HelloWorld/main.py {configuration:/Message}"
      }
    }
  ]
}
```

```
---
...
Manifests:
  - Platform:
      os: all
    Artifacts:
      - URI: "s3://BUCKET_NAME/COMPONENT_NAME/COMPONENT_VERSION/HelloWorld.zip"
        Unarchive: ZIP
    Lifecycle:
      Run: "python3 -u {artifacts:decompressedPath}/HelloWorld/main.py {configuration:/Message}"
```

**Synopsis**  

```
$ gdk component init
    [--language]
    [--template]
    [--repository]
    [--name]
```

**Arguments (initialize from component template)**  
+ `-l`, `--language` – The programming language to use for the template that you specify.

  You must specify either `--repository` or `--language` and `--template`.
+ `-t`, `--template` – The component template to use for a local component project. To view available templates, use the [list](#greengrass-development-kit-cli-component-list) command.

  You must specify either `--repository` or `--language` and `--template`.
+ `-n`, `--name` – (Optional) The name of the local folder where the GDK CLI initializes the component. Specify a folder that doesn't exist. The GDK CLI creates the folder for you.

  This feature is available for GDK CLI v1.1.0 and later.

**Arguments (initialize from community component)**  
+ `-r`, `--repository` – The community component to check out into the local folder. To view available community components, use the [list](#greengrass-development-kit-cli-component-list) command.

  You must specify either `--repository` or `--language` and `--template`.
+ `-n`, `--name` – (Optional) The name of the local folder where the GDK CLI initializes the component. Specify a folder that doesn't exist. The GDK CLI creates the folder for you.

  This feature is available for GDK CLI v1.1.0 and later.

**Output**  
The following example shows the output produced when you run this command to initialize a component folder from the Python Hello World template.  

```
$ gdk component init -l python -t HelloWorld
[2021-11-29 12:51:40] INFO - Initializing the project directory with a python component template - 'HelloWorld'.
[2021-11-29 12:51:40] INFO - Fetching the component template 'HelloWorld-python' from Greengrass Software Catalog.
```
The following example shows the output produced when you run this command to initialize a component folder from a community component.  

```
$ gdk component init -r aws-greengrass-labs-database-influxdb
[2022-01-24 15:44:33] INFO - Initializing the project directory with a component from repository catalog - 'aws-greengrass-labs-database-influxdb'.
[2022-01-24 15:44:33] INFO - Fetching the component repository 'aws-greengrass-labs-database-influxdb' from Greengrass Software Catalog.
```

## build


Build a component's source into a recipe and artifacts that you can publish to the AWS IoT Greengrass service. The GDK CLI runs the build system that you specify in the [GDK CLI configuration file](gdk-cli-configuration-file.md), `gdk-config.json`. You must run this command in the same folder where the `gdk-config.json` file exists.

When you run this command, the GDK CLI creates a recipe and artifacts in the `greengrass-build` folder in the component folder. The GDK CLI saves the recipe in the `greengrass-build/recipes` folder and saves the artifacts in the `greengrass-build/artifacts/componentName/componentVersion` folder.

If you use GDK CLI v1.1.0 or later, the component recipe can specify artifacts that exist in an S3 bucket but not in the local component build folder. You can use this feature to reduce bandwidth usage when you develop components with large artifacts, such as machine learning models.

After you build a component, you can do one of the following to test it on a Greengrass core device:
+ If you develop on a different device than where you run the AWS IoT Greengrass Core software, you must publish the component to deploy it to a Greengrass core device. Publish the component to the AWS IoT Greengrass service, and deploy it to the Greengrass core device. For more information, see the [publish](#greengrass-development-kit-cli-component-build) command and [Create deployments](create-deployments.md).
+ If you develop on the same device where you run the AWS IoT Greengrass Core software, you can publish the component to the AWS IoT Greengrass service to deploy, or you can create a local deployment to install and run the component. To create a local deployment, use the Greengrass CLI. For more information, see [Greengrass Command Line Interface](gg-cli.md) and [Test AWS IoT Greengrass components with local deployments](test-components.md). When you create the local deployment, specify `greengrass-build/recipes` as the recipes folder and `greengrass-build/artifacts` as the artifacts folder.

**Synopsis**  

```
$ gdk component build
```

**Arguments**  
None

**Output**  
The following example shows the output produced when you run this command.  

```
$ gdk component build
[2021-11-29 13:18:49] INFO - Getting project configuration from gdk-config.json
[2021-11-29 13:18:49] INFO - Found component recipe file 'recipe.yaml' in the  project directory.
[2021-11-29 13:18:49] INFO - Building the component 'com.example.PythonHelloWorld' with the given project configuration.
[2021-11-29 13:18:49] INFO - Using 'zip' build system to build the component.
[2021-11-29 13:18:49] WARNING - This component is identified as using 'zip' build system. If this is incorrect, please exit and specify custom build command in the 'gdk-config.json'.
[2021-11-29 13:18:49] INFO - Zipping source code files of the component.
[2021-11-29 13:18:49] INFO - Copying over the build artifacts to the greengrass component artifacts build folder.
[2021-11-29 13:18:49] INFO - Updating artifact URIs in the recipe.
[2021-11-29 13:18:49] INFO - Creating component recipe in 'C:\Users\MyUser\Documents\greengrass-components\python\HelloWorld\greengrass-build\recipes'.
```

## publish


Publish this component to the AWS IoT Greengrass service. This command uploads build artifacts to an S3 bucket, updates the artifact URI in the recipe, and creates a new version of component from the recipe. The GDK CLI uses the S3 bucket and AWS Region that you specify in the [GDK CLI configuration file](gdk-cli-configuration-file.md), `gdk-config.json`. You must run this command in the same folder where the `gdk-config.json` file exists.

<a name="gdk-cli-s3-bucket-name-formation"></a>If you use GDK CLI v1.1.0 or later, you can specify the `--bucket` argument to specify the S3 bucket where the GDK CLI uploads the component's artifacts. <a name="gdk-cli-s3-bucket-name-formation-format"></a>If you don't specify this argument, the GDK CLI uploads to the S3 bucket whose name is `bucket-region-accountId`, where *bucket* and *region* are the values that you specify in `gdk-config.json`, and *accountId* is your AWS account ID. The GDK CLI creates the bucket if it doesn't exist.

If you use GDK CLI v1.2.0 or later, You can override the AWS Region specified in the GDK CLI configuration file using the `--region` parameter. You can also specify additional options using the `--options` parameter. For a list of available options, see [Greengrass Development Kit CLI configuration file](gdk-cli-configuration-file.md).

When you run this command, the GDK CLI publishes the component with the version that you specify in the recipe. If you specify `NEXT_PATCH`, the GDK CLI uses the next patch version that doesn't already exist. Semantic versions use a *major*.*minor*.*patch* numbering system. For more information, see the [semantic version specification](https://semver.org/).

**Note**  
If you use GDK CLI v1.1.0 or later, when you run this command, the GDK CLI checks if the component is built. If the component isn't built, the GDK CLI [builds the component](#greengrass-development-kit-cli-component-build) before it publishes the component.

**Synopsis**  

```
$ gdk component publish
    [--bucket] [--region] [--options]
```

**Arguments**  
+ `-b`, `--bucket` – (Optional) Specify the name of the S3 bucket where the GDK CLI publishes component artifacts.

   <a name="gdk-cli-s3-bucket-name-formation-format"></a>If you don't specify this argument, the GDK CLI uploads to the S3 bucket whose name is `bucket-region-accountId`, where *bucket* and *region* are the values that you specify in `gdk-config.json`, and *accountId* is your AWS account ID. The GDK CLI creates the bucket if it doesn't exist. 

  The GDK CLI creates the bucket if it doesn't exist.

  This feature is available for GDK CLI v1.1.0 and later.
+ `-r`, `--region` – (Optional) Specify the name of the AWS Region to when the component is created. This argument overrides the Region name in the GDK CLI configuration.

  This feature is available for GDK CLI v1.2.0 and later.
+ `-o`, `--options` (Optional) Specify a list of options for publishing a component. The argument must be a valid JSON string or a file path to a JSON file containing the publishing options. This argument overrides the options in the GDK CLI configuration. 

  This feature is available for GDK CLI v1.2.0 and later.

**Output**  
The following example shows the output produced when you run this command.  

```
$ gdk component publish
[2021-11-29 13:45:29] INFO - Getting project configuration from gdk-config.json
[2021-11-29 13:45:29] INFO - Found component recipe file 'recipe.yaml' in the  project directory.
[2021-11-29 13:45:29] INFO - Found credentials in shared credentials file: ~/.aws/credentials
[2021-11-29 13:45:30] INFO - Publishing the component 'com.example.PythonHelloWorld' with the given project configuration.
[2021-11-29 13:45:30] INFO - No private version of the component 'com.example.PythonHelloWorld' exist in the account. Using '1.0.0' as the next version to create.
[2021-11-29 13:45:30] INFO - Uploading the component built artifacts to s3 bucket.
[2021-11-29 13:45:30] INFO - Uploading component artifacts to S3 bucket: {bucket}. If this is your first time using this bucket, add the 's3:GetObject' permission to each core device's token exchange role to allow it to download the component artifacts. For more information, see https://docs.aws.amazon.com/greengrass/v2/developerguide/device-service-role.html.
[2021-11-29 13:45:30] INFO - Not creating an artifacts bucket as it already exists.
[2021-11-29 13:45:30] INFO - Updating the component recipe com.example.PythonHelloWorld-1.0.0.
[2021-11-29 13:45:30] INFO - Creating a new greengrass component com.example.PythonHelloWorld-1.0.0
[2021-11-29 13:45:30] INFO - Created private version '1.0.0' of the component in the account.'com.example.PythonHelloWorld'.
```

## list


Retrieve the list of available component templates and community components.

<a name="gdk-cli-component-templates-community-components"></a>The GDK CLI retrieves community components from the [Greengrass Software Catalog](greengrass-software-catalog.md) and component templates from the [AWS IoT Greengrass Component Templates repository on GitHub](https://github.com/aws-greengrass/aws-greengrass-component-templates).

You can pass the output of this command to the [init](#greengrass-development-kit-cli-component-init) command to initialize component repositories from templates and community components.

**Synopsis**  

```
$ gdk component list
    [--template]
    [--repository]
```

**Arguments**  
+ `-t`, `--template` – (Optional) Specify this argument to list available component templates. This command outputs the name and language of each template in the format `name-language`. For example, in `HelloWorld-python`, the template name is `HelloWorld` and the language is `python`.
+ `-r`, `--repository` – (Optional) Specify this argument to list available community component repositories.

**Output**  
The following example shows the output produced when you run this command.  

```
$ gdk component list --template
[2021-11-29 12:29:04] INFO - Listing all the available component templates from Greengrass Software Catalog.
[2021-11-29 12:29:04] INFO - Found '2' component templates to display.
1. HelloWorld-python
2. HelloWorld-java
```

# config


Use the `config` command in the AWS IoT Greengrass Development Kit Command-Line Interface (GDK CLI) to modify the configuration for the GDK in the configuration file, `gdk-config.json`.

**Topics**
+ [

## update
](#greengrass-development-kit-cli-config-update)

## update


Start an interactive prompt to modify fields within an existing GDK configuration file.

**Synopsis**  

```
$ gdk config update
    [--component]
```

**Arguments**  
+ `-c`, `--component` – To update component-related fields in the `gdk-config.json` file. This argument is required since it is the only option.

**Output**  
The following example shows the output produced when you run this command to configure a component.  

```
$ gdk config update --component
Current value of the REQUIRED component_name is (default: com.example.PythonHelloWorld): 
Current value of the REQUIRED author is (default: author): 
Current value of the REQUIRED version is (default: NEXT_PATCH): 
Do you want to change the build configurations? (y/n) 
Do you want to change the publish configurations? (y/n)
[2023-09-26 10:19:48] INFO - Config file has been updated. Exiting...
```

# test-e2e


Use the `test-e2e` command in the AWS IoT Greengrass Development Kit Command-Line Interface (GDK CLI) to initialize, build, and run end-to-end test modules in the GDK project.

**Topics**
+ [

## init
](#greengrass-development-kit-cli-test-init)
+ [

## build
](#greengrass-development-kit-cli-test-build)
+ [

## run
](#greengrass-development-kit-cli-test-run)

## init


Initialize an existing GDK CLI project with a testing module that uses Greengrass Testing Framework (GTF).

By default, GDK CLI retrieves the maven module template from the [AWS IoT Greengrass Component Templates repository on GitHub](https://github.com/aws-greengrass/aws-greengrass-component-templates). This maven module comes with a dependency on the `aws-greengrass-testing-standalone` JAR file.

This command creates a new directory called `gg-e2e-tests` inside of the GDK project. If the testing module directory already exists and is not empty, the command exits without doing anything. This `gg-e2e-tests` folder contains the Cucumber feature and step definitions structured in a maven project.

By default, this command will try to use the latest release version of GTF.

**Synopsis**  

```
$ gdk test-e2e init
    [--gtf-version]
```

**Arguments**  
+ `-ov`, `--gtf-version` – (Optional) The version of the GTF to use with the end-to-end testing module in the GDK project. This value must be one of the GTF versions from [ releases](https://github.com/aws-greengrass/aws-greengrass-testing/releases). This argument overrides the `gtf_version` in the GDK CLI configuration.

**Output**  
The following example shows the output produced when you run this command to initialize the GDK project with the testing module.  

```
$ gdk test-e2e init
[2023-12-06 12:20:28] INFO - Using the GTF version provided in the GDK test config 1.2.0
[2023-12-06 12:20:28] INFO - Downloading the E2E testing template from GitHub into gg-e2e-tests directory...
```

## build


**Note**  
You must build the component by running **gdk component build** before building the end-to-end test module.

Build the end-to-end testing module. The GDK CLI builds the testing module using the build system that you specify in the [GDK CLI configuration file](gdk-cli-configuration-file.md), `gdk-config.json`, under the `test-e2e` property. You must run this command in the same folder where the `gdk-config.json` file exists.

By default, GDK CLI uses maven build system to build the testing module. [Maven](https://maven.apache.org/) is required to run the `gdk test-e2e build` command.

You must build the component by running **gdk-component-build** before building the testing module, if the test feature files have variables like `GDK_COMPONENT_NAME` and `GDK_COMPONENT_RECIPE_FILE` to interpolate.

When you run this command, the GDK CLI interpolates all of the variables from the GDK project configuration and builds the `gg-e2e-tests` module to generate the final testing JAR file.

**Synopsis**  

```
$ gdk test-e2e build
```

**Arguments**  
None

**Output**  
The following example shows the output produced when you run this command.  

```
$ gdk test-e2e build
[2023-07-20 15:36:48] INFO - Updating feature file: file:///path/to//HelloWorld/greengrass-build/gg-e2e-tests/src/main/resources/greengrass/features/component.feature
[2023-07-20 15:36:48] INFO - Creating the E2E testing recipe file:///path/to/HelloWorld/greengrass-build/recipes/e2e_test_recipe.yaml
[2023-07-20 15:36:48] INFO - Building the E2E testing module
[2023-07-20 15:36:48] INFO - Running the build command 'mvn package'
.........
```

## run


Run the testing module with the testing options in the GDK configuration file.

**Note**  
You must build the testing module by running **gdk test-e2e build** before running the end-to-end tests.

**Synopsis**  

```
$ gdk test-e2e run
    [--gtf-options]
```

**Arguments**  
+ `-oo`, `--gtf-options` – (Optional) Specify a list of options for running the end-to-end tests. The argument must be a valid JSON string or a file path to a JSON file containing the GTF options. The options provided in the configuration file are merged with the ones provided in the command arguments. If an option is present in both places, the one in argument takes precendence over the one from the configuration file.

  If the `tags` option is not specified in this command, GDK uses `Sample` for tags. If `ggc-archive` is not specified, GDK downloads the latest version of the Greengrass nucleus archive.

**Output**  
The following example shows the output produced when you run this command.  

```
$ gdk test-e2e run
[2023-07-20 16:35:53] INFO - Downloading latest nucleus archive from url https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-latest.zip
[2023-07-20 16:35:57] INFO - Running test jar with command java -jar /path/to/greengrass-build/gg-e2e-tests/target/uat-features-1.0.0.jar —ggc-archive=/path/to/aws-greengrass-gdk-cli/HelloWorld/greengrass-build/greengrass-nucleus-latest.zip —tags=Sample

16:35:59.693 [] [] [] [INFO] com.aws.greengrass.testing.modules.GreengrassContextModule - Extracting /path/to/workplace/aws-greengrass-gdk-cli/HelloWorld/greengrass-build/greengrass-nucleus-latest.zip into /var/folders/7g/ltzcb_3s77nbtmkzfb6brwv40000gr/T/gg-testing-7718418114158172636/greengrass
16:36:00.534 [gtf-1.1.0-SNAPSHOT] [] [] [INFO] com.aws.greengrass.testing.features.LoggerSteps - GTF Version is gtf-1.1.0-SNAPSHOT
.......
```

# Greengrass Development Kit CLI configuration file
GDK CLI configuration file

The AWS IoT Greengrass Development Kit Command-Line Interface (GDK CLI) reads from a configuration file named `gdk-config.json` to build and publish components. This configuration file must exist in the root of the component repository. You can use the GDK CLI [init command](greengrass-development-kit-cli-component.md#greengrass-development-kit-cli-component-init) to initialize component repositories with this configuration file.

**Topics**
+ [

## GDK CLI configuration file format
](#gdk-config-format)
+ [

## GDK CLI configuration file examples
](#gdk-config-examples)

## GDK CLI configuration file format


When you define a GDK CLI configuration file for a component, you specify the following information in JSON format.

`gdk_version`  
The minimum version of the GDK CLI that is compatible with this component. This value must be one of the GDK CLI versions from [ releases](https://github.com/aws-greengrass/aws-greengrass-gdk-cli/releases).

`component`  
The configuration for this component.    
`componentName`    
`author`  
The author or publisher of the component.  
`version`  
The version of the component. Specify one of the following:  <a name="gdk-cli-configuration-file-component-version-options"></a>
+ `NEXT_PATCH` – When you choose this option, the GDK CLI sets the version when you publish the component. The GDK CLI queries the AWS IoT Greengrass service to identify the latest published version of the component. Then, it sets the version to the next patch version after that version. If you haven't published the component before, the GDK CLI uses version `1.0.0`.

  If you choose this option, you can't use the [Greengrass CLI](greengrass-cli-component.md) to locally deploy and test the component to your local development computer that runs the AWS IoT Greengrass Core software. To enable local deployments, you must specify a semantic version instead.
+ A semantic version, such as **1.0.0**. Semantic versions use a *major*.*minor*.*patch* numbering system. For more information, see the [semantic version specification](https://semver.org/).

  If you develop components on a Greengrass core device where you want to deploy and test the component, choose this option. You must build the component with a specific version to create local deployments with the [Greengrass CLI](greengrass-cli-component.md).  
`build`  
The configuration to use to build this component's source into artifacts. This object contains the following information:    
  `build_system`   
The build system to use. Choose from the following options:  <a name="gdk-cli-configuration-file-component-build-system-options"></a>
+ `zip` – Packages the component's folder into a ZIP file to define as the component's only artifact. Choose this option for the following types of components:
  + Components that use interpreted programming languages, such as Python or JavaScript.
  + Components that package files other than code, such as machine learning models or other resources.

  The GDK CLI zips the component's folder into a zip file with the same name as the component folder. For example, if the component folder's name is `HelloWorld`, the GDK CLI creates a zip file named `HelloWorld.zip`.
**Note**  
If you use GDK CLI version 1.0.0 on a Windows device, the component folder and zip file names must contain only lowercase letters.

  When the GDK CLI zips the component's folder into a zip file, it skips the following files:
  + The `gdk-config.json` file
  + The recipe file (`recipe.json` or `recipe.yaml`)
  + Build folders, such as `greengrass-build`
+ `maven` – Runs the `mvn clean package` command to build the component's source into artifacts. Choose this option for components that use [Maven](https://maven.apache.org/), such as Java components.

  On Windows devices, this feature is available for GDK CLI v1.1.0 and later.
+ `gradle` – Runs the `gradle build` command to build the component's source into artifacts. Choose this option for components that use [Gradle](https://gradle.org/). This feature is available for GDK CLI v1.1.0 and later.

  The `gradle` build system supports Kotlin DSL as the build file. This feature is available for GDK CLI v1.2.0 and later.
+ `gradlew` – Runs the `gradlew` command to build the component's source into artifacts. Choose this option for components that use the [Gradle Wrapper ](https://docs.gradle.org/current/userguide/gradle_wrapper.html).

  This feature is available for GDK CLI v1.2.0 and later.
+ `custom` – Runs a custom command to build the component's source into a recipe and artifacts. Specify the custom command in the `custom_build_command` parameter.  
`custom_build_command`  
(Optional) The custom build command to run for a custom build system. You must specify this parameter if you specify `custom` for `build_system`.  
This command must create a recipe and artifacts in the following folders within the component folder. The GDK CLI creates these folders for you when you run the [component build command](greengrass-development-kit-cli-component.md#greengrass-development-kit-cli-component-build).  
+ Recipe folder: `greengrass-build/recipes`
+ Artifacts folder: `greengrass-build/artifacts/componentName/componentVersion`

  Replace *componentName* with the component name, and replace *componentVersion* with the component version or `NEXT_PATCH`.
You can specify a single string or a list of strings, where each string is a word in the command. For example, to run a custom build command for a C\$1\$1 component, you might specify **cmake --build build --config Release** or **["cmake", "--build", "build", "--config", "Release"]**.  
To view an example of a custom build system, see the [aws.greengrass.labs.LocalWebServer community component on GitHub](https://github.com/awslabs/aws-greengrass-labs-local-web-server).  
`options`  
(Optional) Additional configuration options used during the component build process.  
This feature is available for GDK CLI v1.2.0 and later.    
`excludes`  
A list of glob patterns that define which files to exclude from the component directory when building the zip file. Only valid when the `build_system` is `zip`.  
In GDK CLI versions 1.4.0 and earlier, any file that matches an entry in the excludes list is excluded from all of the component's subdirectories. To achieve the same behavior in GDK CLI versions 1.5.0 and later, prepend `**/` to the existing entries in the excludes list. For example, `*.txt` will exclude text files from just the directory; `**/*.txt` will exclude text files from all directories and subdirectories.  
In GDK CLI versions 1.5.0 and later, you may see a warning during the component build when `excludes` is defined in the GDK configuration file. To disable this warning, set the environment variable `GDK_EXCLUDES_WARN_IGNORE` to `true`.
The GDK CLI always excludes the following files from the zip file:  
+ The `gdk-config.json` file
+ The recipe file (`recipe.json` or `recipe.yaml`)
+ Build folders, such as `greengrass-build`
The following files are excluded by default. However, you can control which of these files are excluded with the `excludes` option.  
+ Any folder that starts with the prefix "test" (`test*`)
+ All hidden files
+ The `node_modules` folder
If you specify the `excludes` option, the GDK CLI excludes only those files you set with the `excludes` option. If you don't specify the `excludes` option, the GDK CLI excludes the previously noted default files and folders.  
`zip_name`  
The zip file name to use when you create a zip artifact during the build process. Only valid when the `build_system` is `zip`. If the `build_system` is empty, the component name is used for the zip file name.  
`publish`  
The configuration to use to publish this component to the AWS IoT Greengrass service.  
<a name="gdk-cli-s3-bucket-name-formation"></a>If you use GDK CLI v1.1.0 or later, you can specify the `--bucket` argument to specify the S3 bucket where the GDK CLI uploads the component's artifacts. <a name="gdk-cli-s3-bucket-name-formation-format"></a>If you don't specify this argument, the GDK CLI uploads to the S3 bucket whose name is `bucket-region-accountId`, where *bucket* and *region* are the values that you specify in `gdk-config.json`, and *accountId* is your AWS account ID. The GDK CLI creates the bucket if it doesn't exist.  
This object contains the following information:    
`bucket`  
The S3 bucket name to use to host component artifacts.  
`region`  
The AWS Region where the GDK CLI publishes this component.  
This property is optional if you are using GDK CLI v1.3.0 or later.  
`options`  
(Optional) Additional configuration options used during component version creation.  
This feature is available for GDK CLI v1.2.0 and later.    
`file_upload_args`  
A JSON structure containing arguments sent to Amazon S3 while uploading files to a bucket, such as metadata and encryption mechanisms. For a list of the allowed arguments, see the [https://boto3.amazonaws.com/v1/documentation/api/latest/reference/customizations/s3.html#boto3.s3.transfer.S3Transfer.ALLOWED_UPLOAD_ARGS](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/customizations/s3.html#boto3.s3.transfer.S3Transfer.ALLOWED_UPLOAD_ARGS) class in the *Boto3 documentation.*.

`test-e2e`  
(Optional) The configuration to use during end-to-end testing of the component. This feature is available for GDK CLI v1.3.0 and later.    
`build`  
`build_system` – The build system to use. Default option is `maven`. Choose from the following options:  
+ `maven` – Runs the `mvn package` command to build the testing module. Choose this option for building the testing module that uses [Maven](https://maven.apache.org/).
+ `gradle` – Runs the `gradle build` command to build the testing module. Choose this option for the testing module that uses [Gradle](https://gradle.org/).   
`gtf_version`  
(Optional) The version of the Greengrass Testing Framework (GTF) to use as a dependency of the end-to-end testing module when you initialize the GDK project with GTF. This value must be one of the GTF versions from [ releases](https://github.com/aws-greengrass/aws-greengrass-testing/releases). The default is GTF version 1.1.0.  
`gtf_options`  
(Optional) Additional configuration options used during the end-to-end testing of the component.  
<a name="gtf_options"></a>The following list includes the options you can use with GTF version 1.1.0.  
+ `additional-plugins` – (Optional) Additional Cucumber plugins
+ `aws-region` – Targets specific regional endpoints for AWS services. Defaults to what the AWS SDK discovers.
+ `credentials-path` – Optional AWS profile credentials path. Defaults to credentials discovered on host environment.
+ `credentials-path-rotation` – Optional rotation duration for AWS credentials. Defaults to 15 minutes or `PT15M`.
+ `csr-path` – The path for the CSR using which the device certificate will be generated.
+ `device-mode` – The target device under test. Defaults to local device.
+ `env-stage` – Targets the deployment environment of Greengrass. Defaults to production.
+ `existing-device-cert-arn` – The arn of an existing certificate that you want to use as a device certificate for Greengrass.
+ `feature-path` – File or directory containing additional feature files. Default is no additional feature files are used.
+ `gg-cli-version` – Overrides the version of the Greengrass CLI. Defaults to the value found in `ggc.version`.
+ `gg-component-bucket` – The name of an existing Amazon S3 bucket that houses Greengrass components.
+ `gg-component-overrides` – A list of Greengrass component overrides.
+ `gg-persist` – A list of test elements to persist after a test run. Default behavior is to persist nothing. Accepted values are: `aws.resources`, `installed.software`, and `generated.files`.
+ `gg-runtime` – A list of values to influence how the test interacts with testing resources. These values supersede the `gg.persist` parameter. If the default is empty, it assumes all testing resources are manged by test case, including the installed Greengrass runtime. Accepted values are: `aws.resources`, `installed.software`, and `generated.files`.
+ `ggc-archive` – The path to the archived Greengrass nucleus component.
+ `ggc-install-root` – Directory to install the Greengrass nucleus component. Defaults to test.temp.path and test run folder.
+ `ggc-log-level` – Set the Greengrass nucleus log level for the test run. Default is "INFO".
+ `ggc-tes-rolename` – The IAM role that AWS IoT Greengrass Core will assume to access AWS services. If a role with given name does not exist then one will be created and default access policy.
+ `ggc-trusted-plugins` – The comma separate list of the paths (on host) of the trusted plugins that need to added to Greengrass. To provide the path on the DUT itself, prefix the path with 'dut:'
+ `ggc-user-name` – The user:group posixUser value for the Greengrass nucleus. Defaults to the current username that is logged in.
+ `ggc-version` – Overrides the version of the running Greengrass nucleus component. Defaults to the value found in ggc.archive.
+ `log-level` – Log level of the test run. Defaults to "INFO".
+ `parallel-config` – Set of batch index and number of batches as a JSON String. Default value of batch index is 0 and number of batches is 1.
+ `proxy-url` – Configure all tests to route traffic through this URL.
+ `tags` – Only run feature tags. Can be intersected with '&'
+ `test-id-prefix` – A common prefix applied to all test specific resources including AWS resource names and tags. Default is a "gg" prefix.
+ `test-log-path` – Directory that will contain the results of the entire test run. Defaults to "testResults".
+ `test-results-json` – Flag to determine if a resulting Cucumber JSON report is generated written to disk. Defaults to true.
+ `test-results-log` – Flag to determine if the console output is generated written to disk. Defaults to false.
+ `test-results-xml` – Flag to determine if a resulting JUnit XML report is generated written to disk. Defaults to true.
+ `test-temp-path` – Directory to generate local test artifacts. Defaults to a random temp directory prefixed with gg-testing.
+ `timeout-multiplier` – Multiplier provided to all test timeouts. Default is 1.0.

## GDK CLI configuration file examples


You can reference the following GDK CLI configuration file examples to help you configure Greengrass component environments.

### Hello World (Python)


The following GDK CLI configuration file supports a Hello World component that runs a Python script. This configuration file uses the `zip` build system to package the component's Python script into a ZIP file that the GDK CLI uploads as an artifact.

```
{
  "component": {
    "com.example.PythonHelloWorld": {
      "author": "Amazon",
      "version": "NEXT_PATCH",
      "build": {
        "build_system" : "zip",
        "options": {
           "excludes": [".*"]
        }
      },
      "publish": {
        "bucket": "greengrass-component-artifacts",
        "region": "us-west-2",
        "options": {
           "file_upload_args": {
              "Metadata": {
                 "some-key": "some-value"
              }
           }
        }
      }
    },
  "test-e2e":{
    "build":{
        "build_system": "maven"
    },
    "gtf_version": "1.1.0",
    "gtf_options": { 
         "tags": "Sample"
     }
  },
  "gdk_version": "1.6.1"
  }
}
```

### Hello World (Java)


The following GDK CLI configuration file supports a Hello World component that runs a Java application. This configuration file uses the `maven` build system to package the component's Java source code into a JAR file that the GDK CLI uploads as an artifact.

```
{
  "component": {
    "com.example.JavaHelloWorld": {
      "author": "Amazon",
      "version": "NEXT_PATCH",
      "build": {
        "build_system" : "maven"
      },
      "publish": {
        "bucket": "greengrass-component-artifacts",
        "region": "us-west-2",
        "options": {
           "file_upload_args": {
              "Metadata": {
                 "some-key": "some-value"
              }
           }
        }
      }
  },
  "test-e2e":{
    "build":{
        "build_system": "maven"
    },
    "gtf_version": "1.1.0",
    "gtf_options": { 
         "tags": "Sample"
     }
  },
  "gdk_version": "1.6.1"
  }
}
```

### Community components


Several community components in the [Greengrass Software Catalog](greengrass-software-catalog.md) use the GDK CLI. You can explore the GDK CLI configuration files in these components' repositories.

**To view community components' GDK CLI configuration files**

1. Run the following command to list the community components that use the GDK CLI.

   ```
   gdk component list --repository
   ```

   The response lists the name of the GitHub repository for each community component that uses the GDK CLI. Each repository exists in the `awslabs` organization.

   ```
   [2022-02-22 17:27:31] INFO - Listing all the available component repositories from Greengrass Software Catalog.
   [2022-02-22 17:27:31] INFO - Found '6' component repositories to display.
   1. aws-greengrass-labs-database-influxdb
   2. aws-greengrass-labs-telemetry-influxdbpublisher
   3. aws-greengrass-labs-dashboard-grafana
   4. aws-greengrass-labs-dashboard-influxdb-grafana
   5. aws-greengrass-labs-local-web-server
   6. aws-greengrass-labs-lookoutvision-gstreamer
   ```

1. Open a community component's GitHub repository at the following URL. Replace *community-component-name* with the name of a community component from the previous step.

   ```
   https://github.com/awslabs/community-component-name
   ```

# Greengrass Command Line Interface
Greengrass Command Line Interface

The Greengrass Command Line Interface (CLI) lets you interact with AWS IoT Greengrass Core on your device to locally develop components and debug issues. For example, you can use the Greengrass CLI to create a local deployment and restart a component on the core device. 

Deploy the [Greengrass CLI component](greengrass-cli-component.md) (`aws.greengrass.Cli`) to install the Greengrass CLI on your core device.

**Important**  
 <a name="local-dev-tools-production-environment-warning"></a>We recommend that you use this component in only development environments, not production environments. This component provides access to information and operations that you typically won't need in a production environment. Follow the principle of least privilege by deploying this component to only core devices where you need it. 

**Topics**
+ [

# Install the Greengrass CLI
](install-gg-cli.md)
+ [

# Greengrass CLI commands
](gg-cli-reference.md)

# Install the Greengrass CLI


You can install the Greengrass CLI in one of the following ways: 
+ Use the `--deploy-dev-tools` argument when you first set up AWS IoT Greengrass Core software on your device. You must also specify `--provision true` to apply this argument.
+ Deploy the Greengrass CLI component (`aws.greengrass.Cli`) on your device.

This section describes the steps to deploy the Greengrass CLI component. For information about installing the Greengrass CLI during initial setup, see [Tutorial: Getting started with AWS IoT Greengrass V2](getting-started.md).

## Prerequisites


To deploy the Greengrass CLI component, you must meet the following requirements:
+ AWS IoT Greengrass Core software installed and configured on your core device. For more information, see [Tutorial: Getting started with AWS IoT Greengrass V2](getting-started.md). 
+ To use the AWS CLI to deploy the Greengrass CLI, you must have installed and configured the AWS CLI. For more information, see [Configuring the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html) in the *AWS Command Line Interface User Guide*.
+ <a name="greengrass-cli-authorization-requirement"></a>You must be authorized to use the Greengrass CLI to interact with the AWS IoT Greengrass Core software. Do one of the following to use the Greengrass CLI:
  + Use the system user that runs the AWS IoT Greengrass Core software.
  + Use a user with root or adminstrative permissions. On Linux core devices, you can use `sudo` to gain root permissions.
  + Use a system user that's in a group that you specify in the `AuthorizedPosixGroups` or `AuthorizedWindowsGroups` configuration parameters when you deploy the component. For more information, see [Greengrass CLI component configuration](greengrass-cli-component.md#greengrass-cli-component-configuration).

## Deploy the Greengrass CLI component


Complete the following steps to deploy the Greengrass CLI component to your core device:

### To deploy the Greengrass CLI component (console)


1. Sign in to the [AWS IoT Greengrass console](https://console.aws.amazon.com/greengrass).

1. In the navigation menu, choose **Components**.

1. On the **Components** page, on the **Public components** tab, choose `aws.greengrass.Cli`.

1. On the **aws.greengrass.Cli** page, choose **Deploy**.

1. From **Add to deployment**, choose **Create new deployment**.

1. On the **Specify target** page, under **Deployment targets**, in the **Target name** list, choose the Greengrass group that you want to deploy to, and choose **Next**.

1. On the **Select components** page, verify that the **aws.greengrass.Cli** component is selected, and choose **Next**.

1. On the **Configure components** page, keep the default configuration settings, and choose **Next**.

1. On the **Configure advanced setting** page, keep the default configuration settings, and choose **Next**.

1. On the **Review** page, click **Deploy**

### To deploy the Greengrass CLI component (AWS CLI)


1. On your device, create a `deployment.json` file to define the deployment configuration for the Greengrass CLI component. This file should look like the following:

   ```
   {
     "targetArn":"targetArn",
     "components": {
       "aws.greengrass.Cli": {
         "componentVersion": "2.16.1",
         "configurationUpdate": {
           "merge": "{\"AuthorizedPosixGroups\":\"<group1>,<group2>,...,<groupN>\",\"AuthorizedWindowsGroups\":\"<group1>,<group2>,...,<groupN>\"}"
         }
       }
     }
   }
   ```
   + In the `target` field, replace `targetArn` with the Amazon Resource Name (ARN) of the thing or thing group to target for the deployment, in the following format: 
     + Thing: `arn:aws:iot:region:account-id:thing/thingName`
     + Thing group: `arn:aws:iot:region:account-id:thinggroup/thingGroupName`
   + In the `aws.greengrass.Cli` component object, specify values as follows:  
`version`  
The version of the Greengrass CLI component.  
`configurationUpdate.AuthorizedPosixGroups`  
(Optional) A string that contains a comma-separated list of system groups. You authorize these system groups to use the Greengrass CLI to interact with the AWS IoT Greengrass Core software. You can specify group names or group IDs. For example, `group1,1002,group3` authorizes three system groups (`group1`, `1002`, and `group3`) to use the Greengrass CLI.  
If you don't specify any groups to authorize, you can use the Greengrass CLI as the root user (`sudo`) or as the system user that runs the AWS IoT Greengrass Core software.  
`configurationUpdate.AuthorizedWindowsGroups`  
(Optional) A string that contains a comma-separated list of system groups. You authorize these system groups to use the Greengrass CLI to interact with the AWS IoT Greengrass Core software. You can specify group names or group IDs. For example, `group1,1002,group3` authorizes three system groups (`group1`, `1002`, and `group3`) to use the Greengrass CLI.  
If you don't specify any groups to authorize, you can use the Greengrass CLI as an administrator or as the system user that runs the AWS IoT Greengrass Core software.

1. Run the following command to deploy the Greengrass CLI component on the device:

   ```
   $ aws greengrassv2 create-deployment --cli-input-json file://path/to/deployment.json
   ```

During installation, the component adds a symbolic link to `greengrass-cli` in the `/greengrass/v2/bin` folder on your device, and you run the Greengrass CLI from this path. To run the Greengrass CLI without its absolute path, add your `/greengrass/v2/bin` folder to your PATH variable. To verify the Greengrass CLI installation, run the following command:

------
#### [ Linux or Unix ]

```
/greengrass/v2/bin/greengrass-cli help
```

------
#### [ Windows ]

```
C:\greengrass\v2\bin\greengrass-cli help
```

------

You should see the following output:

```
Usage: greengrass-cli [-hV] [--ggcRootPath=<ggcRootPath>] [COMMAND]
Greengrass command line interface

      --ggcRootPath=<ggcRootPath>
                  The AWS IoT Greengrass V2 root directory.
  -h, --help      Show this help message and exit.
  -V, --version   Print version information and exit.
Commands:
  help                Show help information for a command.
  component           Retrieve component information and stop or restart
                        components.
  deployment          Create local deployments and retrieve deployment status.
  logs                Analyze Greengrass logs.
  get-debug-password  Generate a password for use with the HTTP debug view
                        component.
```

If the `greengrass-cli` isn't found, the deployment might have failed to install the Greengrass CLI. For more information, see [Troubleshooting AWS IoT Greengrass V2](troubleshooting.md).

# Greengrass CLI commands


The Greengrass CLI provides a command line interface to interact locally with your AWS IoT Greengrass core device. Greengrass CLI commands use the following format.

```
$ greengrass-cli <command> <subcommand> [arguments]
```

By default, the `greengrass-cli` executable file in the `/greengrass/v2/bin/` folder interacts with the version of the AWS IoT Greengrass Core software running in the `/greengrass/v2` folder. If you call an executable that is not placed in this location, or if you want to interact with AWS IoT Greengrass Core software in a different location, then you must use one of the following methods to explicitly specify the root path of the AWS IoT Greengrass Core software that you want to interact with:<a name="greengrass-cli-set-root-path"></a>
+ Set the `GGC_ROOT_PATH` environment variable to `/greengrass/v2`.
+ Add the `--ggcRootPath /greengrass/v2` argument to your command as shown in the following example.

  ```
  greengrass-cli --ggcRootPath /greengrass/v2 <command> <subcommand> [arguments]
  ```

You can use the following arguments with any command:
+ Use `--help` for information about a specific Greengrass CLI command. 
+ Use `--version` for information about the Greengrass CLI version.

This section describes the Greengrass CLI commands and provides examples for these commands. The synopsis for each command shows its arguments and their usage. Optional arguments are shown in square brackets.

**Topics**
+ [

# component
](gg-cli-component.md)
+ [

# deployment
](gg-cli-deployment.md)
+ [

# logs
](gg-cli-logs.md)
+ [

# get-debug-password
](gg-cli-get-debug-password.md)

# component


Use the `component` command to interact with local components on your core device. 

**Subcommands**
+ [details](#component-details)
+ [list](#component-list)
+ [restart](#component-restart)
+ [stop](#component-stop)

## details


Retrieve the version, status, and configuration of one component. 

**Synopsis**  

```
greengrass-cli component details --name <component-name> 
```

**Arguments**  
`--name`, `-n`. The component name.

**Output**  
The following example shows the output produced when you run this command.  

```
$ sudo greengrass-cli component details --name MyComponent 

Component Name: MyComponent 
Version: 1.0.0
State: RUNNING
Configuration: null
```

## list


Retrieve the name, version, status, and configuration of each component installed on the device.

**Synopsis**  

```
greengrass-cli component list
```

**Arguments**  
None

**Output**  
The following example shows the output produced when you run this command.  

```
$ sudo greengrass-cli component list

Components currently running in Greengrass:
Component Name: FleetStatusService
Version: 0.0.0
State: RUNNING
Configuration: {"periodicUpdateIntervalSec":86400.0}
Component Name: UpdateSystemPolicyService
Version: 0.0.0
State: RUNNING
Configuration: null
Component Name: aws.greengrass.Nucleus
Version: 2.0.0
State: FINISHED
Configuration: {"awsRegion":"region","runWithDefault":{"posixUser":"ggc_user:ggc_group"},"telemetry":{}}
Component Name: DeploymentService
Version: 0.0.0
State: RUNNING
Configuration: null
Component Name: TelemetryAgent
Version: 0.0.0
State: RUNNING
Configuration: null
Component Name: aws.greengrass.Cli
Version: 2.0.0
State: RUNNING
Configuration: {"AuthorizedPosixGroups":"ggc_user"}
```

## restart


Restart components.

**Synopsis**  

```
greengrass-cli component restart --names <component-name>,...
```

**Arguments**  
`--names`, `-n`. The component name. At least one component name is required. You can specify additional component names, separating each name with a comma.

**Output**  
None

## stop


Stop running components. 

**Synopsis**  

```
greengrass-cli component stop --names <component-name>,...
```

**Arguments**  
`--names`, `-n`. The component name. At least one component name is required. You can specify additional component names if needed, separating each name with a comma.

**Output**  
None

# deployment


Use the `deployment` command to interact with local components on your core device. 

To monitor the progress of a local deployment, use the `status` subcommand. You can't monitor the progress of a local deployment using the console.

**Subcommands**
+ [create](#deployment-create)
+ [cancel](#deployment-cancel)
+ [list](#deployment-list)
+ [status](#deployment-status)

## create


Create or update a local deployment using specified component recipes, artifacts, and runtime arguments.

**Synopsis**  

```
greengrass-cli deployment create 
    --recipeDir path/to/component/recipe
    [--artifactDir path/to/artifact/folder ]
    [--update-config {component-configuration}]
    [--groupId <thing-group>]
    [--merge "<component-name>=<component-version>"]...
    [--runWith "<component-name>:posixUser=<user-name>[:<group-name>]"]...
    [--systemLimits "{component-system-resource-limits}]"]...
    [--remove <component-name>,...]
    [--failure-handling-policy <policy name[ROLLBACK, DO_NOTHING]>]
```

**Arguments**  
+ `--recipeDir`, `-r`. The full path to the folder that contains the component recipe files.
+ `--artifactDir`, `-a`. The full path to the folder that contains the artifact files you want to include in your deployment. The artifacts folder must contain the following directory structure:

  ```
  /path/to/artifact/folder/<component-name>/<component-version>/<artifacts>
  ```
+ `--update-config`, `-c`. The configuration arguments for the deployment, provided as a JSON string or a JSON file. The JSON string should be in the following format: 

  ```
  { \
    "componentName": { \ 
      "MERGE": {"config-key": "config-value"}, \
      "RESET": ["path/to/reset/"] \
    } \
  }
  ```

  `MERGE` and `RESET` are case-sensitive and must be in upper case.
+ `--groupId`, `-g`. The target thing group for the deployment.
+ `--merge`, `-m`. The name and version of the target component that you want to add or update. You must provide the component information in the format `<component>=<version>`. Use a separate argument for each additional component to specify. If needed, use the `--runWith` argument to provide the `posixUser`, `posixGroup`, and `windowsUser` information for running the component.
+ `--runWith`. The `posixUser`, `posixGroup`, and `windowsUser` information for running a generic or Lambda component. You must provide this information in the format `<component>:{posixUser|windowsUser}=<user>[:<=posixGroup>]`. For example, you might specify **HelloWorld:posixUser=ggc\$1user:ggc\$1group** or **HelloWorld:windowsUser=ggc\$1user**. Use a separate argument for each additional option to specify.

  For more information, see [Configure the user that runs components](configure-greengrass-core-v2.md#configure-component-user).
+ `--systemLimits`. The system resource limits to apply to generic and non-containerized Lambda components' processes on the core device. You can configure the maximum amount of CPU and RAM usage that each component's processes can use. Specify a serialized JSON object or a file path to a JSON file. The JSON object must have the following format.

  ```
  {  \
    "componentName": { \ 
      "cpus": cpuTimeLimit, \
      "memory": memoryLimitInKb \
    } \
  }
  ```

  You can configure the following system resource limits for each component:
  + `cpus` – <a name="system-resource-limits-cpu-definition-this"></a>The maximum amount of CPU time that this component's processes can use on the core device. A core device's total CPU time is equivalent to the device's number of CPU cores. For example, on a core device with 4 CPU cores, you can set this value to `2` to limit this component's processes to 50 percent usage of each CPU core. On a device with 1 CPU core, you can set this value to `0.25` to limit this component's processes to 25 percent usage of the CPU. If you set this value to a number greater than the number of CPU cores, the AWS IoT Greengrass Core software doesn't limit the component's CPU usage. 
  + `memory` – <a name="system-resource-limits-memory-definition-this"></a>The maximum amount of RAM (in kilobytes) that this component's processes can use on the core device. 

  For more information, see [Configure system resource limits for components](configure-greengrass-core-v2.md#configure-component-system-resource-limits).

  This feature is available for v2.4.0 and later of the [Greengrass nucleus component](greengrass-nucleus-component.md) and Greengrass CLI on Linux core devices. AWS IoT Greengrass doesn't currently support this feature on Windows core devices. 
+ `--remove`. The name of the target component that you want to remove from a local deployment. To remove a component that was merged from a cloud deployment, you must provide the group ID of the target thing group in the following format:

------
#### [ Greengrass nucleus v2.4.0 and later ]

  ```
  --remove <component-name> --groupId <group-name>
  ```

------
#### [ Earlier than v2.4.0 ]

  ```
  --remove <component-name> --groupId thinggroup/<group-name>
  ```

------
+ `--failure-handling-policy`. Defines the action taken when a deployment fails. There are two actions that you can specify:
  + `ROLLBACK` – 
  + `DO_NOTHING` – 

  This feature is available for v2.11.0 and later of the [Greengrass nucleus](greengrass-nucleus-component.md).

**Output**  
The following example shows the output produced when you run this command.  

```
$ sudo greengrass-cli deployment create \
    --merge MyApp1=1.0.0 \
    --merge MyApp2=1.0.0 --runWith MyApp2:posixUser=ggc_user \
    --remove MyApp3 \
    --recipeDir recipes/ \ 
    --artifactDir artifacts/

Local deployment has been submitted! Deployment Id: 44d89f46-1a29-4044-ad89-5151213dfcbc
```

## cancel


Cancels the specified deployment.

Synopsis  

```
greengrass-cli deployment cancel
    -i <deployment-id>
```

Arguments  
`-i`. The unique identifier of the deployment to cancel. The deployment ID is returned in the output of the `create` command.

Output  
+ None

## list


Retrieve the status of the last 10 local deployments.

**Synopsis**  

```
greengrass-cli deployment list
```

**Arguments**  
None

**Output**  
The following example shows the output produced when you run this command. Depending on the status of your deployment, the output shows one of the following status values: `IN_PROGRESS`, `SUCCEEDED`, or `FAILED`.  

```
$ sudo greengrass-cli deployment list

44d89f46-1a29-4044-ad89-5151213dfcbc: SUCCEEDED
Created on: 6/27/23 11:05 AM
```

## status


Retrieve the status of a specific deployment.

**Synopsis**  

```
greengrass-cli deployment status -i <deployment-id>
```

**Arguments**  
`-i`. The ID of the deployment.

**Output**  
The following example shows the output produced when you run this command. Depending on the status of your deployment, the output shows one of the following status values: `IN_PROGRESS`, `SUCCEEDED`, or `FAILED`.  

```
$ sudo greengrass-cli deployment status -i 44d89f46-1a29-4044-ad89-5151213dfcbc

44d89f46-1a29-4044-ad89-5151213dfcbc: FAILED
Created on: 6/27/23 11:05 AM
Detailed Status: <Detailed deployment status>
Deployment Error Stack: List of error codes
Deployment Error Types: List of error types
Failure Cause: Cause
```

# logs


Use the `logs` command to analyze Greengrass logs on your core device. 

**Subcommands**
+ [get](#logs-get)
+ [list-keywords](#logs-list-keywords)
+ [list-log-files](#logs-list-log-files)

## get


Collect, filter, and visualize Greengrass log files. This command supports only JSON-formatted log files. You can specify the [logging format](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-logging-format) in the nucleus configuration.

**Synopsis**  

```
greengrass-cli logs get
    [--log-dir path/to/a/log/folder]
    [--log-file path/to/a/log/file]
    [--follow true | false ]
    [--filter <filter> ]
    [--time-window <start-time>,<end-time> ]
    [--verbose ]
    [--no-color ]
    [--before <value> ]
    [--after <value> ]
    [--syslog ]
    [--max-long-queue-size <value> ]
```

**Arguments**  
+ `--log-dir`, `-ld`. The path to the directory to check for log files, such as **`/greengrass/v2`/logs**. Do not use with `--syslog`. Use a separate argument for each additional directory to specify. You must use at least one of `--log-dir` or `--log-file`. You can also use both arguments in a single command. 
+ `--log-file`, `-lf`. The paths to the log directories you want to use. Use a separate argument for each additional directory to specify. You must use at least one of `--log-dir` or `--log-file`. You can also use both arguments in a single command.
+ `--follow`, `-fol`. Show log updates as they occur. Greengrass CLI continues to run and reads from the specified logs. If you specify a time window, then Greengrass CLI stops monitoring logs after all of the time windows end.
+ `--filter`, `-f`. The keyword, regular expressions, or key-value pair to use as a filter. Provide this value as a string, a regular expression, or as a key-value pair. Use a separate argument for each additional filter to specify. 

  When evaluated, multiple filters specified in a single argument are separated by OR operators, and filters specified in additional arguments are combined with AND operators. For example, if your command includes `--filter "installed" --filter "name=alpha,name=beta"`, then Greengrass CLI will filter and display log messages that contain both the keyword `installed` and a `name` key that has the values `alpha` or `beta`.
+ `--time-window`, `-t`. The time window for which to show log information. You can use both exact timestamps and relative offsets. You must provide this information in the format `<begin-time>,<end-time>`. If you do not specify either the begin time or the end time, then the value for that option defaults to the current system date and time. Use a separate argument for each additional time window to specify. 

  Greengrass CLI supports the following formats for timestamps:
  + `yyyy-MM-DD`, for example, `2020-06-30`. The time defaults to 00:00:00 when you use this format.

    `yyyyMMDD`, for example, `20200630`. The time defaults to 00:00:00 when you use this format.

    `HH:mm:ss`, for example, `15:30:45`. The date defaults to the current system date when you use this format.

    `HH:mm:ssSSS`, for example, `15:30:45`. The date defaults the current system date when you use this format.

    `YYYY-MM-DD'T'HH:mm:ss'Z'`, for example, `2020-06-30T15:30:45Z`.

    `YYYY-MM-DD'T'HH:mm:ss`, for example, `2020-06-30T15:30:45`. 

    `yyyy-MM-dd'T'HH:mm:ss.SSS`, for example, `2020-06-30T15:30:45.250`.

  Relative offsets specify a time period offset from the current system time. Greengrass CLI supports the following format for relative offsets: `+|-[<value>h|hr|hours][valuem|min|minutes][value]s|sec|seconds`. 

  For example, the following argument to specify a time window between 1 hour and 2 hours 15 minutes before the current time is `--time-window -2h15min,-1hr`.
+ `--verbose`. Show all fields from the log messages. Do not use with `--syslog`.
+ `--no-color`, `-nc`. Remove color coding. The default color coding for log messages uses bold red text. Supports only UNIX-like terminals because it uses ANSI escape sequences.
+ `--before`, `-b`. The number of lines to show preceding a matched log entry. Default is 0.
+ `--after`, `-a`. The number of lines to show following a matched log entry. Default is 0.
+ `--syslog`. Process all log files using the syslog protocol defined by RFC3164. Do not use with `--log-dir` and `--verbose`. The syslog protocol uses the following format: `"<$Priority>$Timestamp $Host $Logger ($Class): $Message"`. If you do not specify a log file, then Greengrass CLI reads log messages from the following locations: `/var/log/messages`, `/var/log/syslog`, or the `/var/log/system.log`. 

  AWS IoT Greengrass doesn't currently support this feature on Windows core devices. 
+ `--max-log-queue-size`, `-m`. The maximum number of log entries to allocate to memory. Use this option to optimize memory usage. Default is 100.

**Output**  
The following example shows the output produced when you run this command.  

```
$ sudo greengrass-cli logs get --verbose \
    --log-file /greengrass/v2/logs/greengrass.log \
    --filter deployment,serviceName=DeploymentService \
    --filter level=INFO \
    --time-window 2020-12-08T01:11:17,2020-12-08T01:11:22

2020-12-08T01:11:17.615Z [INFO] (pool-2-thread-14) com.aws.greengrass.deployment.DeploymentService: Current deployment finished. {DeploymentId=44d89f46-1a29-4044-ad89-5151213dfcbc, serviceName=DeploymentService, currentState=RUNNING}
2020-12-08T01:11:17.675Z [INFO] (pool-2-thread-14) com.aws.greengrass.deployment.IotJobsHelper: Updating status of persisted deployment. {Status=SUCCEEDED, StatusDetails={detailed-deployment-status=SUCCESSFUL}, ThingName=MyThing, JobId=22d89f46-1a29-4044-ad89-5151213dfcbc
```

## list-keywords


Show suggested keywords that you can use to filter log files.

**Synopsis**  

```
greengrass-cli logs list-keywords [arguments]
```

**Arguments**  
None

**Output**  
The following examples show the output produced when you run this command.  

```
$ sudo greengrass-cli logs list-keywords

Here is a list of suggested keywords for Greengrass log:
level=$str
thread=$str
loggerName=$str
eventType=$str
serviceName=$str
error=$str
```

```
$ sudo greengrass-cli logs list-keywords --syslog

Here is a list of suggested keywords for syslog:
priority=$int
host=$str
logger=$str
class=$str
```

## list-log-files


Show log files located in a specified directory.

**Synopsis**  

```
greengrass-cli logs list-log-files [arguments]
```

**Arguments**  
`--log-dir`, `-ld`. The path to the directory to check for log files. 

**Output**  
The following example shows the output produced when you run this command.  

```
$ sudo greengrass-cli logs list-log-files -ld /greengrass/v2/logs/

/greengrass/v2/logs/aws.greengrass.Nucleus.log
/greengrass/v2/logs/main.log
/greengrass/v2/logs/greengrass.log
Total 3 files found.
```

# get-debug-password


Use the `get-debug-password` command to print a randomly generated password for the [local debug console component](local-debug-console-component.md) (`aws.greengrass.LocalDebugConsole`). The password expires 8 hours after it is generated.

**Synopsis**  

```
greengrass-cli get-debug-password
```

**Arguments**  
None

**Output**  
The following example shows the output produced when you run this command.  

```
$ sudo greengrass-cli get-debug-password

Username: debug
Password: bEDp3MOHdj8ou2w5de_sCBI2XAaguy3a8XxREXAMPLE
Password expires at: 2021-04-01T17:01:43.921999931-07:00
The local debug console is configured to use TLS security. The certificate is self-signed so you will need to bypass your web browser's security warnings to open the console.
Before you bypass the security warning, verify that the certificate fingerprint matches the following fingerprints.
SHA-256: 15 0B 2C E2 54 8B 22 DE 08 46 54 8A B1 2B 25 DE FB 02 7D 01 4E 4A 56 67 96 DA A6 CC B1 D2 C4 1B
SHA-1: BC 3E 16 04 D3 80 70 DA E0 47 25 F9 90 FA D6 02 80 3E B5 C1
```

# Use AWS IoT Greengrass Testing Framework
Use Greengrass Testing FrameworkGreengrass Testing Framework[https://docs.aws.amazon.com/greengrass/v2/developerguide/gg-testing-framework.html](https://docs.aws.amazon.com/greengrass/v2/developerguide/gg-testing-framework.html)

GTF is a collection of building blocks to support end-to-end automation. It enables AWS IoT Greengrass Version 2 internal customers to use the same testing framework that the service team uses for qualifying software changes, automated acceptance, and quality assurance purposes.

Greengrass Testing Framework (GTF) is a collection of building blocks that supports end-to-end automation from the customer perspective. GTF uses [Cucumber](https://cucumber.io) as the feature driver. AWS IoT Greengrass uses the same building blocks to qualify software changes on various devices. For more information, see [Greengrass Testing Framework on Github](https://github.com/aws-greengrass/aws-greengrass-testing/tree/dev_v1).

GTF is implemented using Cucumber, a tool used to run automated tests, to encourage a Behavior-Driven Development (BDD) of the components. In Cucumber, the features of this system are outlined in a special type of file called `feature`. Each feature is described in a human-readable format called scenarios which are specifications that can be converted into automated tests. Each scenario is outlined as a series of steps that define the interactions and outcomes of this system under test using a domain-specific language called Gherkin. A [Gherkin step](https://cucumber.io/docs/gherkin/reference/#steps) is linked to the programming code using a method called step definition which hard wires the specification to the test flow. Step definitions in GTF are implemented with Java.

**Topics**
+ [

## How it works
](#gg-testing-framework-how-gtf-works)
+ [

## Changelog
](#gtf-changelog)
+ [

# Greengrass Testing Framework configuration options
](configuration-options-gtf.md)
+ [

# Tutorial: Run end-to-end tests using Greengrass Testing Framework and Greengrass Development Kit
](run-e2e-tests-tutorial.md)
+ [

# Tutorial: Use a confidence test from the confidence test suite
](confidence-tests-tutorial.md)

## How it works


AWS IoT Greengrass distributes the GTF as a standalone JAR that consists of several Java modules. To use GTF for end-to-end testing of components, you must implement the tests within a Java project. Adding the testing standable JAR as a dependency in your Java project enables you to use the existing functionality of the GTF and extend it by writing your own custom test cases. To run the custom test cases, you can build your Java project and run the target JAR with the configuration options described in [Greengrass Testing Framework configuration options](configuration-options-gtf.md).

### GTF standalone JAR


Greengrass uses Cloudfront as a [Maven](https://maven.apache.org/) repository to host different versions of the GTF standalone JAR. For a full list of GTF versions, see [GTF releases](https://github.com/aws-greengrass/aws-greengrass-testing/releases).

GTF standalone JAR includes the following modules. It is not limited to only these modules. You can pick and choose each of these dependencies separately in your project or include all of them at once with the [testing standalone JAR file](https://github.com/aws-greengrass/aws-greengrass-testing/tree/dev_v1/aws-greengrass-testing-standalone).
+ `aws-greengrass-testing-resources`: This module provides abstraction for managing the lifecycle of an AWS resource during the course of a test. You can use this to define your custom AWS resources using `ResourceSpec` abstraction so GTF can take care of creation and removal of those resources for you.
+ `aws-greengrass-testing-platform`: This module provides platform-level abstraction for the device under test during the test lifecycle. It contains APIs used to interact with the OS independent of the platform and can be used to simulate the commands running in the device shell.
+ `aws-greengrass-testing-components`: This module consists of sample components that are used for testing the Greengrass core features such as deployments, IPC, and other features.
+ `aws-greengrass-testing-features`: This module consists of reusable common steps and their definitions which are used for testing within in the Greengrass environment.

**Topics**
+ [

## How it works
](#gg-testing-framework-how-gtf-works)
+ [

## Changelog
](#gtf-changelog)
+ [

# Greengrass Testing Framework configuration options
](configuration-options-gtf.md)
+ [

# Tutorial: Run end-to-end tests using Greengrass Testing Framework and Greengrass Development Kit
](run-e2e-tests-tutorial.md)
+ [

# Tutorial: Use a confidence test from the confidence test suite
](confidence-tests-tutorial.md)

## Changelog


The following table describes the changes in each version of the GTF. For more information, see the [GTF Releases page](https://github.com/aws-greengrass/aws-greengrass-testing/releases) on GitHub.


|  **Version**  |  **Changes**  | 
| --- | --- | 
| 1.2.0 |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/gg-testing-framework.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/gg-testing-framework.html)  | 
|  1.1.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/gg-testing-framework.html)  | 
|  1.0.0  |  Initial version.  | 

# Greengrass Testing Framework configuration options
GTF configuration options

## GTF configuration options


Greengrass Testing Framework (GTF) enables you to configure certain parameters during the launch of the end-to-end testing process to orchestrate the test flow. You can specify these configuration options as CLI arguments for the GTF standalone JAR.

<a name="gtf_options"></a>GTF version 1.1.0 and later provides the following configuration options.
+ `additional-plugins` – (Optional) Additional Cucumber plugins
+ `aws-region` – Targets specific regional endpoints for AWS services. Defaults to what the AWS SDK discovers.
+ `credentials-path` – Optional AWS profile credentials path. Defaults to credentials discovered on host environment.
+ `credentials-path-rotation` – Optional rotation duration for AWS credentials. Defaults to 15 minutes or `PT15M`.
+ `csr-path` – The path for the CSR using which the device certificate will be generated.
+ `device-mode` – The target device under test. Defaults to local device.
+ `env-stage` – Targets the deployment environment of Greengrass. Defaults to production.
+ `existing-device-cert-arn` – The arn of an existing certificate that you want to use as a device certificate for Greengrass.
+ `feature-path` – File or directory containing additional feature files. Default is no additional feature files are used.
+ `gg-cli-version` – Overrides the version of the Greengrass CLI. Defaults to the value found in `ggc.version`.
+ `gg-component-bucket` – The name of an existing Amazon S3 bucket that houses Greengrass components.
+ `gg-component-overrides` – A list of Greengrass component overrides.
+ `gg-persist` – A list of test elements to persist after a test run. Default behavior is to persist nothing. Accepted values are: `aws.resources`, `installed.software`, and `generated.files`.
+ `gg-runtime` – A list of values to influence how the test interacts with testing resources. These values supersede the `gg.persist` parameter. If the default is empty, it assumes all testing resources are manged by test case, including the installed Greengrass runtime. Accepted values are: `aws.resources`, `installed.software`, and `generated.files`.
+ `ggc-archive` – The path to the archived Greengrass nucleus component.
+ `ggc-install-root` – Directory to install the Greengrass nucleus component. Defaults to test.temp.path and test run folder.
+ `ggc-log-level` – Set the Greengrass nucleus log level for the test run. Default is "INFO".
+ `ggc-tes-rolename` – The IAM role that AWS IoT Greengrass Core will assume to access AWS services. If a role with given name does not exist then one will be created and default access policy.
+ `ggc-trusted-plugins` – The comma separate list of the paths (on host) of the trusted plugins that need to added to Greengrass. To provide the path on the DUT itself, prefix the path with 'dut:'
+ `ggc-user-name` – The user:group posixUser value for the Greengrass nucleus. Defaults to the current username that is logged in.
+ `ggc-version` – Overrides the version of the running Greengrass nucleus component. Defaults to the value found in ggc.archive.
+ `log-level` – Log level of the test run. Defaults to "INFO".
+ `parallel-config` – Set of batch index and number of batches as a JSON String. Default value of batch index is 0 and number of batches is 1.
+ `proxy-url` – Configure all tests to route traffic through this URL.
+ `tags` – Only run feature tags. Can be intersected with '&'
+ `test-id-prefix` – A common prefix applied to all test specific resources including AWS resource names and tags. Default is a "gg" prefix.
+ `test-log-path` – Directory that will contain the results of the entire test run. Defaults to "testResults".
+ `test-results-json` – Flag to determine if a resulting Cucumber JSON report is generated written to disk. Defaults to true.
+ `test-results-log` – Flag to determine if the console output is generated written to disk. Defaults to false.
+ `test-results-xml` – Flag to determine if a resulting JUnit XML report is generated written to disk. Defaults to true.
+ `test-temp-path` – Directory to generate local test artifacts. Defaults to a random temp directory prefixed with gg-testing.
+ `timeout-multiplier` – Multiplier provided to all test timeouts. Default is 1.0.

# Tutorial: Run end-to-end tests using Greengrass Testing Framework and Greengrass Development Kit
Tutorial: Run end-to-end tests using GTF and GDK

AWS IoT Greengrass Testing Framework (GTF) and Greengrass Development Kit (GDK) offer developers ways to run end-to-end tests. You can complete this tutorial to initialize a GDK project with a component, initialize a GDK project with an end-to-end test module, and build a custom test case. After you build your custom test case, you can then run the test.

In this tutorial, you do the following:

1. Initialize a GDK project with a component.

1. Initialize a GDK project with an end-to-end test module.

1. Build a custom test case.

1. Add a tag to the new test case.

1. Build the test JAR.

1. Run the test.

**Topics**
+ [

## Prerequisites
](#run-e2e-tests-tutorial-prerequisites)
+ [

## Step 1: Initialize a GDK project with a component
](#init-gdk-with-component)
+ [

## Step 2: Initialize a GDK project with an end-to-end test module
](#init-gdk-with-e2e-test)
+ [

## Step 3: Build a custom test case
](#run-e2e-tests-tutorial-instructions)
+ [

## Step 4: Add a tag to the new test case
](#add-tag-to-test-case)
+ [

## Step 5: Build the test JAR
](#build-test-jar)
+ [

## Step 6: Run the test
](#run-test-gtf)
+ [

## Example: Build a custom test case
](#build-test-case-example)

## Prerequisites


To complete this tutorial, you need the following:
+ GDK version 1.3.0 or later
+ Java
+ Maven
+ Git

## Step 1: Initialize a GDK project with a component

+ Initialize an empty folder with a GDK project. Download the `HelloWorld` component implemented in Python by running the following command.

  ```
  gdk component init -t HelloWorld -l python -n HelloWorld
  ```

  This command creates a new directory named `HelloWorld` in the current directory.

## Step 2: Initialize a GDK project with an end-to-end test module

+ GDK enables you to download the testing module template consisting of a feature and step implementation. Run the following command to open the `HelloWorld` directory and initialize the existing GDK project using a testing module.

  ```
  cd HelloWorld
  gdk test-e2e init
  ```

  This command creates a new directory named `gg-e2e-tests` within the `HelloWorld` directory. This test directory is a [Maven](https://maven.apache.org/) project which has a dependency on the Greengrass testing standalone JAR.

## Step 3: Build a custom test case


Writing a custom test case broadly consists of two steps: create a feature file with a test scenario and implement step definitions. For an example of building a custom test case, see [Example: Build a custom test case](#build-test-case-example). Use the following steps to build your custom test case:

1. Create a feature file with a test scenario

   A feature typically describes a specific functionality of the software that is being tested. In Cucumber, each feature is specified as an individual feature file with a title, a detailed description, and one or more examples of specific cases called scenarios. Each scenario consists of a title, a detailed description, and a series of steps that define the interactions and expected outcomes. Scenarios are written in a structured format using "given," "when," and "then" keywords.

1. Implement step definitions

   A step definition links the [Gherkin step](https://cucumber.io/docs/gherkin/reference/#steps) in plain language to the programmatic code. When Cucumber identifies a Gherkin step in a scenario, it will look for a matching step definition to run.

## Step 4: Add a tag to the new test case

+ You can assign tags to the features and scenarios to organize the test process. You can use tags to categorize the subsets of scenarios and also select hooks conditionally to run. Features and scenarios can have multiple tags separated by a space.

  In this example, we are using the `HelloWorld` component.

  In the feature file, add a new tag named `@HelloWorld` beside the `@Sample` tag.

  ```
  @Sample @HelloWorld
  Scenario: As a developer, I can create a component and deploy it on my device
  ....
  ```

## Step 5: Build the test JAR


1. Build the component. You must build the component before building the test module.

   ```
   gdk component build
   ```

1. Build the test module using the following command. This command will build the testing JAR in the `greengrass-build` folder.

   ```
   gdk test-e2e build
   ```

## Step 6: Run the test


When you run a custom test case, the GTF automates the lifecycle of the test along with managing resources that were created during the test. It first provisions a device under test (DUT) as an AWS IoT thing and installs the Greengrass core software on it. It will then create a new component named `HelloWorld` using the recipe specified in that path. The `HelloWorld` component is then deployed onto the core device through a Greengrass thing deployment. It will then be verified if the deployment is successful. The deployment status will changed to `COMPLETED` within 3 minutes if the deployment is successful.

1. Go to the `gdk-config.json` file in the project directory to target the tests with the `HelloWorld` tag. Update the the `test-e2e` key using the following command.

   ```
     "test-e2e":{
       "gtf_options" : { 
            "tags":"HelloWorld"
        }
     }
   ```

1. Before running the tests, you must provide AWS credentials to the host device. GTF uses these credentials to manage the AWS resources during the testing process. Make sure the role you provide has permissions to automate the necessary operations that are included in the test.

   Run the following commands to provide the AWS credentials.

   1. 

------
#### [ 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. Run the test using the following command.

   ```
   gdk test-e2e run
   ```

   This command downloads the latest version of the Greengrass nucleus in the `greengrass-build` folder and runs tests using it. This command also targets only the scenarios with the `HelloWorld` tag and generates a report for those scenarios. You will see the AWS resources that were created during this test are discarded at the end of the test.

## Example: Build a custom test case


**Example**  
The downloaded testing module in the GDK project consists of a sample feature and a step implementation file.  
In the following example, we create a feature file for testing the thing deployment feature of the Greengrass software. We partially test the functionality of this feature with a scenario that performs deployment of a component through the Greengrass AWS Cloud. This is a series of steps that help us to understand the interactions and expected outcomes of this use case.  <a name="build-test-case-example-steps"></a>

1. 

**Create a feature file**

   Navigate to the `gg-e2e-tests/src/main/resources/greengrass/features` folder in the current directory. You can find the sample `component.feature` that looks like the following example.

   In this feature file, you can test the thing deployment feature of the Greengrass software. You can partially test the functionality of this feature with a scenario that performs a deployment of a component through the Greengrass cloud. The scenario is a series of steps that help with understanding the interactions and expected outcomes of this use case.

   ```
   Feature: Testing features of Greengrassv2 component
   
   Background:
       Given my device is registered as a Thing
       And my device is running Greengrass
   
   @Sample
   Scenario: As a developer, I can create a component and deploy it on my device
       When I create a Greengrass deployment with components
           HelloWorld | /path/to/recipe/file
       And I deploy the Greengrass deployment configuration
       Then the Greengrass deployment is COMPLETED on the device after 180 seconds
       And I call my custom step
   ```

   GTF contains the step definitions of all of the following steps, except for the step named: `And I call my custom step`.

1. 

**Implement step definitions**

   GTF standalone JAR contains the step definitions of all of the steps except for one step: `And I call my custom step`. You can implement this step in the testing module.

   Navigate to the source code of the testing file. You can link your custom step using a step definition by using the following command.

   ```
   @And("I call my custom step")
   public void customStep() {
       System.out.println("My custom step was called ");
   }
   ```

# Tutorial: Use a confidence test from the confidence test suite
Tutorial: Use a confidence test from the confidence test suite

AWS IoT Greengrass Testing Framework (GTF) and Greengrass Development Kit (GDK) offer developers ways to run end-to-end tests. You can complete this tutorial to initialize a GDK project with a component, initialize a GDK project with an end-to-end test module, and use a confidence test from the confidence test suite. After you build your custom test case, you can then run the test.

A confidence test is a generic test provided by Greengrass that validates fundamental component behaviors. These tests can be modified or extended to fit more specific component needs. 

For this tutorial we will be using a HelloWorld component. If you are using another component, replace the HelloWorld component with your component.

In this tutorial, you do the following:

1. Initialize a GDK project with a component.

1. Initialize a GDK project with an end-to-end test module.

1. Use a test from the confidence test suite.

1. Add a tag to the new test case.

1. Build the test JAR.

1. Run the test.

**Topics**
+ [

## Prerequisites
](#confidence-tests-tutorial-prerequisites)
+ [

## Step 1: Initialize a GDK project with a component
](#init-gdk-with-component)
+ [

## Step 2: Initialize a GDK project with an end-to-end test module
](#init-gdk-with-e2e-test)
+ [

## Step 3: Use a test from the confidence test suite
](#confidence-tests-tutorial-instructions)
+ [

## Step 4: Add a tag to the new test case
](#add-tag-to-test-case)
+ [

## Step 5: Build the test JAR
](#build-test-jar)
+ [

## Step 6: Run the test
](#run-test-gtf)
+ [

## Example: Use a confidence test
](#build-confidence-test-case-example)

## Prerequisites


To complete this tutorial, you need the following:
+ GDK version 1.6.0 or later
+ Java
+ Maven
+ Git

## Step 1: Initialize a GDK project with a component

+ Initialize an empty folder with a GDK project. Download the `HelloWorld` component implemented in Python by running the following command.

  ```
  gdk component init -t HelloWorld -l python -n HelloWorld
  ```

  This command creates a new directory named `HelloWorld` in the current directory.

## Step 2: Initialize a GDK project with an end-to-end test module

+ GDK enables you to download the testing module template consisting of a feature and step implementation. Run the following command to open the `HelloWorld` directory and initialize the existing GDK project using a testing module.

  ```
  cd HelloWorld
  gdk test-e2e init
  ```

  This command creates a new directory named `gg-e2e-tests` within the `HelloWorld` directory. This test directory is a [Maven](https://maven.apache.org/) project which has a dependency on the Greengrass testing standalone JAR.

## Step 3: Use a test from the confidence test suite


Writing a confidence test case consists of using the provided feature file and, if needed, modifying the scenarios. For an example of using a confidence test, see [Example: Build a custom test case](run-e2e-tests-tutorial.md#build-test-case-example). Use the following steps to use a confidence test:
+ Use the provided feature file.

  Navigate to `gg-e2e-tests/src/main/resources/greengrass/features` folder in the current directory. Open the sample `confidenceTest.feature` file to use the confidence test.

## Step 4: Add a tag to the new test case

+ You can assign tags to the features and scenarios to organize the test process. You can use tags to categorize the subsets of scenarios and also select hooks conditionally to run. Features and scenarios can have multiple tags separated by a space.

  In this example, we are using the `HelloWorld` component.

  Each scenario is tagged with `@ConfidenceTest`. Change or add tags if you want to run only a subset of the test suite. Each test scenario is described at the top of each confidence test. The scenario is a series of steps that help with understanding the interactions and expected outcomes of each test case. You can extend these tests by adding your own steps or by modifying the existing ones.

  ```
  @ConfidenceTest
  Scenario: As a Developer, I can deploy GDK_COMPONENT_NAME to my device and see it is working as expected
  ....
  ```

## Step 5: Build the test JAR


1. Build the component. You must build the component before building the test module.

   ```
   gdk component build
   ```

1. Build the test module using the following command. This command will build the testing JAR in the `greengrass-build` folder.

   ```
   gdk test-e2e build
   ```

## Step 6: Run the test


When you run a confidence test, the GTF automates the lifecycle of the test along with managing resources that were created during the test. It first provisions a device under test (DUT) as an AWS IoT thing and installs the Greengrass core software on it. It will then create a new component named `HelloWorld` using the recipe specified in that path. The `HelloWorld` component is then deployed onto the core device through a Greengrass thing deployment. It will then be verified if the deployment is successful. The deployment status will changed to `COMPLETED` within 3 minutes if the deployment is successful.

1. Go to the `gdk-config.json` file in the project directory to target the tests with the `ConfidenceTest` tag or whichever tag yo8u specified in Step 4. Update the the `test-e2e` key using the following command.

   ```
     "test-e2e":{
       "gtf_options" : { 
            "tags":"ConfidenceTest"
        }
     }
   ```

1. Before running the tests, you must provide AWS credentials to the host device. GTF uses these credentials to manage the AWS resources during the testing process. Make sure the role you provide has permissions to automate the necessary operations that are included in the test.

   Run the following commands to provide the AWS credentials.

   1. 

------
#### [ 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. Run the test using the following command.

   ```
   gdk test-e2e run
   ```

   This command downloads the latest version of the Greengrass nucleus in the `greengrass-build` folder and runs tests using it. This command also targets only the scenarios with the `ConfidenceTest` tag and generates a report for those scenarios. You will see the AWS resources that were created during this test are discarded at the end of the test.

## Example: Use a confidence test


**Example**  
The downloaded testing module in the GDK project consists of a provided feature file.  
In the following example, we use a feature file for testing the thing deployment feature of the Greengrass software. We partially test the functionality of this feature with a scenario that performs deployment of a component through the Greengrass AWS Cloud. This is a series of steps that help us to understand the interactions and expected outcomes of this use case.  <a name="build-confidence-test-case-example-steps"></a>
+ 

**Use the provided feature file.**

  Navigate to the `gg-e2e-tests/src/main/resources/greengrass/features` folder in the current directory. You can find the sample `confidenceTest.feature` that looks like the following example.

  ```
  Feature: Confidence Test Suite
  
  Background:
      Given my device is registered as a Thing
      And my device is running Greengrass
  
  @ConfidenceTest
  Scenario: As a Developer, I can deploy GDK_COMPONENT_NAME to my device and see it is working as expected
      When I create a Greengrass deployment with components
        | GDK_COMPONENT_NAME | GDK_COMPONENT_RECIPE_FILE |
        | aws.greengrass.Cli | LATEST                    |
      And I deploy the Greengrass deployment configuration
      Then the Greengrass deployment is COMPLETED on the device after 180 seconds
      # Update component state accordingly. Possible states: {RUNNING, FINISHED, BROKEN, STOPPING}
      And I verify the GDK_COMPONENT_NAME component is RUNNING using the greengrass-cli
  ```

  Each test scenario is described at the top of each confidence test. The scenario is a series of steps that help with understanding the interactions and expected outcomes of each test case. You can extend these tests by adding your own steps or by modifying the existing ones. Each of the scenarios include comments that help you to make these adjustments.

# Develop AWS IoT Greengrass components
Develop components

You can develop and test components on your Greengrass core device. As a result, you can create and iterate your AWS IoT Greengrass software without interacting with the AWS Cloud. When you finish a version of your component, you can upload it to AWS IoT Greengrass in the cloud, so you and your team can deploy the component to other devices in your fleet. For more information about how to deploy components, see [Deploy AWS IoT Greengrass components to devices](manage-deployments.md).

Every component is composed of a *recipe* and *artifacts*.
+ <a name="component-recipe-definition"></a>**Recipes**

  Every component contains a recipe file, which defines its metadata. The recipe also specifies the component's configuration parameters, component dependencies, lifecycle, and platform compatibility. The component lifecycle defines the commands that install, run, and shut down the component. For more information, see [AWS IoT Greengrass component recipe reference](component-recipe-reference.md).

  You can define recipes in [JSON](https://en.wikipedia.org/wiki/JSON) or [YAML](https://en.wikipedia.org/wiki/YAML) format.
+ <a name="component-artifacts-definition"></a>**Artifacts**

  Components can have any number of artifacts, which are component binaries. Artifacts can include scripts, compiled code, static resources, and any other files that a component consumes. Components can also consume artifacts from component dependencies.

AWS IoT Greengrass provides pre-built components that you can use in your applications and deploy to your devices. For example, you can use the stream manager component to upload data to various AWS services, or you can use the CloudWatch metrics component to publish custom metrics to Amazon CloudWatch. For more information, see [AWS-provided components](public-components.md).

AWS IoT Greengrass curates an index of Greengrass components, called the Greengrass Software Catalog. This catalog tracks Greengrass components that are developed by the Greengrass community. From this catalog, you can download, modify, and deploy components to create your Greengrass applications. For more information, see [Community components](greengrass-software-catalog.md).

The AWS IoT Greengrass Core software runs components as the system user and group, such as `ggc_user` and `ggc_group`, that you configure on the core device. This means that components have the permissions of that system user. If you use a system user without a home directory, then components can't use run commands or code that use a home directory. This means that you can't use the `pip install some-library --user` command to install Python packages for example. If you followed the [getting started tutorial](getting-started.md) to set up your core device, then your system user doesn't have a home directory. For more information about how to configure the user and group that run components, see [Configure the user that runs components](configure-greengrass-core-v2.md#configure-component-user).

**Note**  <a name="semver-note"></a>
<a name="semver-para"></a>AWS IoT Greengrass uses semantic versions for components. Semantic versions follow a *major*.*minor*.*patch* number system. For example, version `1.0.0` represents the first major release for a component. For more information, see the [semantic version specification](https://semver.org/).

**Topics**
+ [

## Component lifecycle
](#component-lifecycle)
+ [

## Component types
](#component-types)
+ [

# Create AWS IoT Greengrass components
](create-components.md)
+ [

# Test AWS IoT Greengrass components with local deployments
](test-components.md)
+ [

# Publish components to deploy to your core devices
](publish-components.md)
+ [

# Interact with AWS services
](interact-with-aws-services.md)
+ [

# Run a Docker container
](run-docker-container.md)
+ [

# AWS IoT Greengrass component recipe reference
](component-recipe-reference.md)
+ [

# Component environment variable reference
](component-environment-variables.md)

## Component lifecycle


The *component lifecycle* defines the stages that the AWS IoT Greengrass Core software uses to install and run components. Each stage defines a script and other information that specifies how the component behaves. For example, when you install a component, the AWS IoT Greengrass Core software runs the `install` lifecycle script for that component. Components on core devices have the following lifecycle states:
+ `NEW` – The component's recipe and artifacts are loaded on the core device, but the component isn't installed. After a component enters this state, it runs its [install script](component-recipe-reference.md#install-lifecycle-definition).
+ `INSTALLED` – The component is installed on the core device. The component enters this state after it runs its [install script](component-recipe-reference.md#install-lifecycle-definition).
+ `STARTING` – The component is starting on the core device. The component enters this state when it runs its [startup script](component-recipe-reference.md#startup-lifecycle-definition). If the startup succeeds, the component enters the `RUNNING` state.
+ `RUNNING` – The component is running on the core device. The component enters this state when it runs its [run script](component-recipe-reference.md#run-lifecycle-definition) or when it has active background processes from its startup script.
+ `FINISHED` – The component ran successfully and completed its run.
+ `STOPPING` – The component is stopping. The component enters this state when it runs its [shutdown script](component-recipe-reference.md#shutdown-lifecycle-definition).
+ `ERRORED` – The component encountered an error. When the component enters this state, it runs its [recover script](component-recipe-reference.md#recover-lifecycle-definition). Then, the component restarts to try returning to normal use. If the component enters the `ERRORED` state three times without a successful run, the component becomes `BROKEN`.
+ `BROKEN` – The component encountered errors multiple times and can't recover. You must deploy the component again to fix it.

## Component types


The *component type* specifies how the AWS IoT Greengrass Core software runs the component. Components can have the following types:
+ **Nucleus** (`aws.greengrass.nucleus`)

  The Greengrass nucleus is the component that provides the minimum functionality of the AWS IoT Greengrass Core software. For more information, see [Greengrass nucleus](greengrass-nucleus-component.md).
+ **Plugin** (`aws.greengrass.plugin`)

  The Greengrass nucleus runs a plugin component in the same Java Virtual Machine (JVM) as the nucleus. The nucleus restarts when you change the version of a plugin component on a core device. To install and run plugin components, you must configure the Greengrass nucleus to run as a system service. For more information, see [Configure the Greengrass nucleus as a system service](configure-greengrass-core-v2.md#configure-system-service).

  Several components that are provided by AWS are plugin components, which enables them to interface directly with the Greengrass nucleus. Plugin components use the same log file as the Greengrass nucleus. For more information, see [Monitor AWS IoT Greengrass logs](monitor-logs.md).
+ **Generic** (`aws.greengrass.generic`)

  The Greengrass nucleus runs a generic component's lifecycle scripts, if the component defines a lifecycle.

  This type is the default type for custom components.
+ **Lambda** (`aws.greengrass.lambda`)

  The Greengrass nucleus runs a Lambda function component using the [Lambda launcher component](lambda-launcher-component.md).

  When you create a component from a Lambda function, the component has this type. For more information, see [Run AWS Lambda functions](run-lambda-functions.md).

**Note**  <a name="recipe-component-type-recommendation"></a>
We don't recommend that you specify the component type in a recipe. AWS IoT Greengrass sets the type for you when you create a component.

# Create AWS IoT Greengrass components
Create components

You can develop custom AWS IoT Greengrass components on a local development computer or a Greengrass core device. AWS IoT Greengrass provides the [AWS IoT Greengrass Development Kit Command-Line Interface (GDK CLI)](greengrass-development-kit-cli.md) to help you create, build, and publish components from predefined component templates and [community components](greengrass-software-catalog.md). You can also run built-in shell commands to create, build, and publish components. Choose from the following options to create custom Greengrass components:
+ **Use the Greengrass Development Kit CLI**

  Use the GDK CLI to develop components on a local development computer. The GDK CLI builds and packages component source code into a recipe and artifacts that you can publish as a private component to the AWS IoT Greengrass service. You can configure the GDK CLI to automatically update the component's version and artifact URIs when you publish the component, so you don't need to update the recipe each time. To develop a component using the GDK CLI, you can start from a template or a community component from the [Greengrass Software Catalog](greengrass-software-catalog.md). For more information, see [AWS IoT Greengrass Development Kit Command-Line Interface](greengrass-development-kit-cli.md).
+ **Run built-in shell commands**

  You can run built-in shell commands to develop components on a local development computer or on a Greengrass core device. You use shell commands to copy or build component source code into artifacts. Each time you create a new version of a component, you must create or update the recipe with the new component version. When you publish the component to the AWS IoT Greengrass service, you must update the URI to each component artifact in the recipe.

**Topics**
+ [

## Create a component (GDK CLI)
](#create-component-gdk-cli)
+ [

## Create a component (shell commands)
](#create-component-shell-commands)

## Create a component (GDK CLI)


Follow instructions in this section to create and build a component using the GDK CLI.

**To develop a Greengrass component (GDK CLI)**

1. If you haven't already, install the GDK CLI on your development computer. For more information, see [Install or update the AWS IoT Greengrass Development Kit Command-Line Interface](install-greengrass-development-kit-cli.md).

1. Change to the folder where you want to create component folders.

------
#### [ Linux or Unix ]

   ```
   mkdir ~/greengrassv2
   cd ~/greengrassv2
   ```

------
#### [ Windows Command Prompt (CMD) ]

   ```
   mkdir %USERPROFILE%\greengrassv2
   cd %USERPROFILE%\greengrassv2
   ```

------
#### [ PowerShell ]

   ```
   mkdir ~/greengrassv2
   cd ~/greengrassv2
   ```

------

1. Choose a component template or community component to download. The GDK CLI downloads the template or community component, so you can start from a functional example. Use the [component list](greengrass-development-kit-cli-component.md#greengrass-development-kit-cli-component-list) command to retrieve the list of available templates or community components.
   + To list component templates, run the following command. Each line in the response includes a template's name and programming language.

     ```
     gdk component list --template
     ```
   + To list community components, run the following command.

     ```
     gdk component list --repository
     ```

1. Create and change to a component folder where the GDK CLI downloads the template or community component. Replace *HelloWorld* with the name of the component, or another name that helps you identify this component folder.

------
#### [ Linux or Unix ]

   ```
   mkdir HelloWorld
   cd HelloWorld
   ```

------
#### [ Windows Command Prompt (CMD) ]

   ```
   mkdir HelloWorld
   cd HelloWorld
   ```

------
#### [ PowerShell ]

   ```
   mkdir HelloWorld
   cd HelloWorld
   ```

------

1. Download the template or community component to the current folder. Use the [component init](greengrass-development-kit-cli-component.md#greengrass-development-kit-cli-component-init) command.
   + To create a component folder from a template, run the following command. Replace *HelloWorld* with the name of the template, and replace *python* with the name of the programming language.

     ```
     gdk component init --template HelloWorld --language python
     ```
   + To create a component folder from a community component, run the following command. Replace *ComponentName* with the name of the community component.

     ```
     gdk component init --repository ComponentName
     ```
**Note**  
<a name="gdk-cli-component-init-empty-folder-requirement"></a>If you use GDK CLI v1.0.0, you must run this command in an empty folder. The GDK CLI downloads the template or community component to the current folder.  
<a name="gdk-cli-component-init-empty-folder-requirement-gdk-cli-v1.1.0"></a>If you use GDK CLI v1.1.0 or later, you can specify the `--name` argument to specify the folder where the GDK CLI downloads the template or community component. If you use this argument, specify a folder that doesn't exist. The GDK CLI creates the folder for you. If you don't specify this argument, the GDK CLI uses the current folder, which must be empty.

1. The GDK CLI reads from the [GDK CLI configuration file](gdk-cli-configuration-file.md), named `gdk-config.json`, to build and publish components. This configuration file exists in the root of the component folder. The previous step creates this file for you. In this step, you update `gdk-config.json` with information about your component. Do the following:

   1. Open `gdk-config.json` in a text editor.

   1. (Optional) Change the name of the component. The component name is the key in the `component` object.

   1. Change the author of the component.

   1. (Optional) Change the version of the component. Specify one of the following:<a name="gdk-cli-configuration-file-component-version-options"></a>
      + `NEXT_PATCH` – When you choose this option, the GDK CLI sets the version when you publish the component. The GDK CLI queries the AWS IoT Greengrass service to identify the latest published version of the component. Then, it sets the version to the next patch version after that version. If you haven't published the component before, the GDK CLI uses version `1.0.0`.

        If you choose this option, you can't use the [Greengrass CLI](greengrass-cli-component.md) to locally deploy and test the component to your local development computer that runs the AWS IoT Greengrass Core software. To enable local deployments, you must specify a semantic version instead.
      + A semantic version, such as **1.0.0**. Semantic versions use a *major*.*minor*.*patch* numbering system. For more information, see the [semantic version specification](https://semver.org/).

        If you develop components on a Greengrass core device where you want to deploy and test the component, choose this option. You must build the component with a specific version to create local deployments with the [Greengrass CLI](greengrass-cli-component.md).

   1. (Optional) Change the build configuration for the component. The build configuration defines how the GDK CLI builds the component's source into artifacts. Choose from the following options for `build_system`:<a name="gdk-cli-configuration-file-component-build-system-options"></a>
      + `zip` – Packages the component's folder into a ZIP file to define as the component's only artifact. Choose this option for the following types of components:
        + Components that use interpreted programming languages, such as Python or JavaScript.
        + Components that package files other than code, such as machine learning models or other resources.

        The GDK CLI zips the component's folder into a zip file with the same name as the component folder. For example, if the component folder's name is `HelloWorld`, the GDK CLI creates a zip file named `HelloWorld.zip`.
**Note**  
If you use GDK CLI version 1.0.0 on a Windows device, the component folder and zip file names must contain only lowercase letters.

        When the GDK CLI zips the component's folder into a zip file, it skips the following files:
        + The `gdk-config.json` file
        + The recipe file (`recipe.json` or `recipe.yaml`)
        + Build folders, such as `greengrass-build`
      + `maven` – Runs the `mvn clean package` command to build the component's source into artifacts. Choose this option for components that use [Maven](https://maven.apache.org/), such as Java components.

        On Windows devices, this feature is available for GDK CLI v1.1.0 and later.
      + `gradle` – Runs the `gradle build` command to build the component's source into artifacts. Choose this option for components that use [Gradle](https://gradle.org/). This feature is available for GDK CLI v1.1.0 and later.

        The `gradle` build system supports Kotlin DSL as the build file. This feature is available for GDK CLI v1.2.0 and later.
      + `gradlew` – Runs the `gradlew` command to build the component's source into artifacts. Choose this option for components that use the [Gradle Wrapper ](https://docs.gradle.org/current/userguide/gradle_wrapper.html).

        This feature is available for GDK CLI v1.2.0 and later.
      + `custom` – Runs a custom command to build the component's source into a recipe and artifacts. Specify the custom command in the `custom_build_command` parameter.

   1. If you specify `custom` for `build_system`, add the `custom_build_command` to the `build` object. In `custom_build_command`, specify a single string or list of strings, where each string is a word in the command. For example, to run a custom build command for a C\$1\$1 component, you might specify **["cmake", "--build", "build", "--config", "Release"]**.

   1. <a name="gdk-cli-s3-bucket-name-formation"></a>If you use GDK CLI v1.1.0 or later, you can specify the `--bucket` argument to specify the S3 bucket where the GDK CLI uploads the component's artifacts. <a name="gdk-cli-s3-bucket-name-formation-format"></a>If you don't specify this argument, the GDK CLI uploads to the S3 bucket whose name is `bucket-region-accountId`, where *bucket* and *region* are the values that you specify in `gdk-config.json`, and *accountId* is your AWS account ID. The GDK CLI creates the bucket if it doesn't exist.

      Change the publish configuration for the component. Do the following:

      1. Specify the name of the S3 bucket to use to host component artifacts.

      1. Specify the AWS Region where the GDK CLI publishes the component.

   When you're done with this step, the `gdk-config.json` file might look similar to the following example.

   ```
   {
     "component": {
       "com.example.PythonHelloWorld": {
         "author": "Amazon",
         "version": "NEXT_PATCH",
         "build": {
           "build_system" : "zip"
         },
         "publish": {
           "bucket": "greengrass-component-artifacts",
           "region": "us-west-2"
         }
       }
     },
     "gdk_version": "1.0.0"
   }
   ```

1. Update the component recipe file, named `recipe.yaml` or `recipe.json`. Do the following:

   1. If you downloaded a template or community component that uses the `zip` build system, check that the zip artifact name matches the name of the component folder. The GDK CLI zips the component folder into a zip file with the same name as the component folder. The recipe contains the zip artifact name in the list of component artifacts and in lifecycle scripts that use files in the zip artifact. Update the `Artifacts` and `Lifecycle` definitions such that the zip file name matches the name of the component folder. The following partial recipe examples highlight the zip file name in the `Artifacts` and `Lifecycle` definitions.

------
#### [ JSON ]

      ```
      {
        ...
        "Manifests": [
          {
            "Platform": {
              "os": "all"
            },
            "Artifacts": [
              {
                "URI": "s3://{COMPONENT_NAME}/{COMPONENT_VERSION}/HelloWorld.zip",
                "Unarchive": "ZIP"
              }
            ],
            "Lifecycle": {
              "Run": "python3 -u {artifacts:decompressedPath}/HelloWorld/main.py {configuration:/Message}"
            }
          }
        ]
      }
      ```

------
#### [ YAML ]

      ```
      ---
      ...
      Manifests:
        - Platform:
            os: all
          Artifacts:
            - URI: "s3://BUCKET_NAME/COMPONENT_NAME/COMPONENT_VERSION/HelloWorld.zip"
              Unarchive: ZIP
          Lifecycle:
            Run: "python3 -u {artifacts:decompressedPath}/HelloWorld/main.py {configuration:/Message}"
      ```

------

   1. (Optional) Update the component description, default configuration, artifacts, lifecycle scripts, and platform support. For more information, see [AWS IoT Greengrass component recipe reference](component-recipe-reference.md).

   When you're done with this step, the recipe file might look similar to the following examples.

------
#### [ JSON ]

   ```
   {
     "RecipeFormatVersion": "2020-01-25",
     "ComponentName": "{COMPONENT_NAME}",
     "ComponentVersion": "{COMPONENT_VERSION}",
     "ComponentDescription": "This is a simple Hello World component written in Python.",
     "ComponentPublisher": "{COMPONENT_AUTHOR}",
     "ComponentConfiguration": {
       "DefaultConfiguration": {
         "Message": "World"
       }
     },
     "Manifests": [
       {
         "Platform": {
           "os": "all"
         },
         "Artifacts": [
           {
             "URI": "s3://{COMPONENT_NAME}/{COMPONENT_VERSION}/HelloWorld.zip",
             "Unarchive": "ZIP"
           }
         ],
         "Lifecycle": {
           "Run": "python3 -u {artifacts:decompressedPath}/HelloWorld/main.py {configuration:/Message}"
         }
       }
     ]
   }
   ```

------
#### [ YAML ]

   ```
   ---
   RecipeFormatVersion: "2020-01-25"
   ComponentName: "{COMPONENT_NAME}"
   ComponentVersion: "{COMPONENT_VERSION}"
   ComponentDescription: "This is a simple Hello World component written in Python."
   ComponentPublisher: "{COMPONENT_AUTHOR}"
   ComponentConfiguration:
     DefaultConfiguration:
       Message: "World"
   Manifests:
     - Platform:
         os: all
       Artifacts:
         - URI: "s3://BUCKET_NAME/COMPONENT_NAME/COMPONENT_VERSION/HelloWorld.zip"
           Unarchive: ZIP
       Lifecycle:
         Run: "python3 -u {artifacts:decompressedPath}/HelloWorld/main.py {configuration:/Message}"
   ```

------

1. Develop and build the Greengrass component. The [component build](greengrass-development-kit-cli-component.md#greengrass-development-kit-cli-component-build) command produces a recipe and artifacts in the `greengrass-build` folder in the component folder. Run the following command.

   ```
   gdk component build
   ```

When you're ready to test your component, use the GDK CLI to publish it to the AWS IoT Greengrass service. Then, you can deploy the component to Greengrass core devices. For more information, see [Publish components to deploy to your core devices](publish-components.md).

## Create a component (shell commands)


Follow instructions in this section to create recipe and artifact folders that contain source code and artifacts for multiple components.

**To develop a Greengrass component (shell commands)**

1. <a name="create-component-recipes-artifacts-folder-step"></a>Create a folder for your components with subfolders for recipes and artifacts. Run the following commands on your Greengrass core device to create these folders and change to the component folder. Replace *\$1/greengrassv2* or *%USERPROFILE%\$1greengrassv2* with the path to the folder to use for local development.

------
#### [ Linux or Unix ]

   ```
   mkdir -p ~/greengrassv2/{recipes,artifacts}
   cd ~/greengrassv2
   ```

------
#### [ Windows Command Prompt (CMD) ]

   ```
   mkdir %USERPROFILE%\greengrassv2\\recipes, %USERPROFILE%\greengrassv2\\artifacts
   cd %USERPROFILE%\greengrassv2
   ```

------
#### [ PowerShell ]

   ```
   mkdir ~/greengrassv2/recipes, ~/greengrassv2/artifacts
   cd ~/greengrassv2
   ```

------

1. <a name="create-component-recipe-file-step"></a>Use a text editor to create a recipe file that defines your component's metadata, parameters, dependencies, lifecycle, and platform capability. Include the component version in the recipe file name so that you can identify which recipe reflects which component version. You can choose YAML or JSON format for your recipe.

   <a name="nano-command-intro"></a>For example, on a Linux-based system, you can run the following command to use GNU nano to create the file.

------
#### [ JSON ]

   ```
   nano recipes/com.example.HelloWorld-1.0.0.json
   ```

------
#### [ YAML ]

   ```
   nano recipes/com.example.HelloWorld-1.0.0.yaml
   ```

------
**Note**  
<a name="semver-para"></a>AWS IoT Greengrass uses semantic versions for components. Semantic versions follow a *major*.*minor*.*patch* number system. For example, version `1.0.0` represents the first major release for a component. For more information, see the [semantic version specification](https://semver.org/).

1. Define the recipe for your component. For more information, see [AWS IoT Greengrass component recipe reference](component-recipe-reference.md).

   Your recipe might look similar to the following Hello World example recipe.

------
#### [ JSON ]

   ```
   {
     "RecipeFormatVersion": "2020-01-25",
     "ComponentName": "com.example.HelloWorld",
     "ComponentVersion": "1.0.0",
     "ComponentDescription": "My first AWS IoT Greengrass component.",
     "ComponentPublisher": "Amazon",
     "ComponentConfiguration": {
       "DefaultConfiguration": {
         "Message": "world"
       }
     },
     "Manifests": [
       {
         "Platform": {
           "os": "linux"
         },
         "Lifecycle": {
           "run": "python3 -u {artifacts:path}/hello_world.py {configuration:/Message}"
         }
       },
       {
         "Platform": {
           "os": "windows"
         },
         "Lifecycle": {
           "run": "py -3 -u {artifacts:path}/hello_world.py {configuration:/Message}"
         }
       }
     ]
   }
   ```

------
#### [ YAML ]

   ```
   ---
   RecipeFormatVersion: '2020-01-25'
   ComponentName: com.example.HelloWorld
   ComponentVersion: '1.0.0'
   ComponentDescription: My first AWS IoT Greengrass component.
   ComponentPublisher: Amazon
   ComponentConfiguration:
     DefaultConfiguration:
       Message: world
   Manifests:
     - Platform:
         os: linux
       Lifecycle:
         run: |
           python3 -u {artifacts:path}/hello_world.py "{configuration:/Message}"
     - Platform:
         os: windows
       Lifecycle:
         run: |
           py -3 -u {artifacts:path}/hello_world.py "{configuration:/Message}"
   ```

------

   This recipe runs a Hello World Python script, which might look similar to the following example script.

   ```
   import sys
   
   message = "Hello, %s!" % sys.argv[1]
   
   # Print the message to stdout, which Greengrass saves in a log file.
   print(message)
   ```

1. Create a folder for the component version to develop. We recommend that you use a separate folder for each component version's artifacts so that you can identify which artifacts are for each component version. Run the following command.

------
#### [ Linux or Unix ]

   ```
   mkdir -p artifacts/com.example.HelloWorld/1.0.0
   ```

------
#### [ Windows Command Prompt (CMD) ]

   ```
   mkdir artifacts/com.example.HelloWorld/1.0.0
   ```

------
#### [ PowerShell ]

   ```
   mkdir artifacts/com.example.HelloWorld/1.0.0
   ```

------
**Important**  <a name="local-artifact-folder-name-requirements"></a>
You must use the following format for the artifact folder path. Include the component name and version that you specify in the recipe.  

   ```
   artifacts/componentName/componentVersion/
   ```

1. Create the artifacts for your component in the folder that you created in the previous step. Artifacts can include software, images, and any other binaries that your component uses.

   When your component is ready, [test your component](test-components.md).

# Test AWS IoT Greengrass components with local deployments
Test components with local deployments

If you develop a Greengrass component on a core device, you can create a local deployment to install and test it. Follow the steps in this section to create a local deployment.

If you develop the component on a different computer, such as a local development computer, you can't create a local deployment. Instead, publish the component to the AWS IoT Greengrass service so that you can deploy it to Greengrass core devices to test it. For more information, see [Publish components to deploy to your core devices](publish-components.md) and [Deploy AWS IoT Greengrass components to devices](manage-deployments.md).

**To test a component on an Greengrass core device**

1. The core device logs events such as component updates. You can view this log file to discover and troubleshoot errors with your component, such as an invalid recipe. This log file also displays messages that your component prints to standard out (stdout). We recommend that you open an additional terminal session on your core device to observe new log messages in real time. Open a new terminal session, such as through SSH, and run the following command to view the logs. Replace `/greengrass/v2` with the path to the AWS IoT Greengrass root folder.

------
#### [ Linux or Unix ]

   ```
   sudo tail -f /greengrass/v2/logs/greengrass.log
   ```

------
#### [ PowerShell ]

   ```
   gc C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
   ```

------

   You can also view the log file for your component.

------
#### [ Linux or Unix ]

   ```
   sudo tail -f /greengrass/v2/logs/com.example.HelloWorld.log
   ```

------
#### [ PowerShell ]

   ```
   gc C:\greengrass\v2\logs\com.example.HelloWorld.log -Tail 10 -Wait
   ```

------

1. In your original terminal session, run the following command to update the core device with your component. Replace `/greengrass/v2` with the path to the AWS IoT Greengrass root folder, and replace *\$1/greengrassv2* with the path to your local development folder.

------
#### [ Linux or Unix ]

   ```
   sudo /greengrass/v2/bin/greengrass-cli deployment create \
     --recipeDir ~/greengrassv2/recipes \
     --artifactDir ~/greengrassv2/artifacts \
     --merge "com.example.HelloWorld=1.0.0"
   ```

------
#### [ Windows Command Prompt (CMD) ]

   ```
   C:\greengrass\v2\bin\greengrass-cli deployment create ^
     --recipeDir %USERPROFILE%\greengrassv2\recipes ^
     --artifactDir %USERPROFILE%\greengrassv2\artifacts ^
     --merge "com.example.HelloWorld=1.0.0"
   ```

------
#### [ PowerShell ]

   ```
   C:\greengrass\v2\bin\greengrass-cli deployment create `
     --recipeDir ~/greengrassv2/recipes `
     --artifactDir ~/greengrassv2/artifacts `
     --merge "com.example.HelloWorld=1.0.0"
   ```

------
**Note**  
You can also use the `greengrass-cli deployment create` command to set the value of your component's configuration parameters. For more information, see [create](gg-cli-deployment.md#deployment-create).

1. Use the `greengrass-cli deployment status` command to monitor the progress of your component's deployment. 

------
#### [ Unix or Linux ]

   ```
   sudo /greengrass/v2/bin/greengrass-cli deployment status \
     -i deployment-id
   ```

------
#### [ Windows Command Prompt (CMD) ]

   ```
   C:\greengrass\v2\bin\greengrass-cli deployment status ^
     -i deployment-id
   ```

------
#### [ PowerShell ]

   ```
   C:\greengrass\v2\bin\greengrass-cli deployment status `
     -i deployment-id
   ```

------

1. Test your component as it runs on the Greengrass core device. When you finish this version of your component, you can upload it to the AWS IoT Greengrass service. Then, you can deploy the component to other core devices. For more information, see [Publish components to deploy to your core devices](publish-components.md).

# Publish components to deploy to your core devices
Publish components to deploy

After you build or complete a version of a component, you can publish it to the AWS IoT Greengrass service. Then, you can deploy it to Greengrass core devices.

If you use the [Greengrass Development Kit CLI (GDK CLI)](greengrass-development-kit-cli.md) to [develop and build a component](create-components.md), you can [use the GDK CLI](#publish-component-gdk-cli) to publish the component to the AWS Cloud. Otherwise, [use built-in shell commands and the AWS CLI](#publish-component-shell-commands) to publish the component.

You can also use AWS CloudFormation to create components and other AWS resources from templates. For more information, see [What is AWS CloudFormation?](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) and [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-greengrassv2-componentversion.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-greengrassv2-componentversion.html) in the *AWS CloudFormation User Guide*.

**Topics**
+ [

## Publish a component (GDK CLI)
](#publish-component-gdk-cli)
+ [

## Publish a component (shell commands)
](#publish-component-shell-commands)

## Publish a component (GDK CLI)


Follow instructions in this section to publish a component using the GDK CLI. The GDK CLI uploads build artifacts to an S3 bucket, updates the artifact URIs in the recipe, and creates the component from the recipe. You specify the S3 bucket and Region to use in the [GDK CLI configuration file](gdk-cli-configuration-file.md).

<a name="gdk-cli-s3-bucket-name-formation"></a>If you use GDK CLI v1.1.0 or later, you can specify the `--bucket` argument to specify the S3 bucket where the GDK CLI uploads the component's artifacts. <a name="gdk-cli-s3-bucket-name-formation-format"></a>If you don't specify this argument, the GDK CLI uploads to the S3 bucket whose name is `bucket-region-accountId`, where *bucket* and *region* are the values that you specify in `gdk-config.json`, and *accountId* is your AWS account ID. The GDK CLI creates the bucket if it doesn't exist.

**Important**  <a name="publish-component-s3-bucket-token-exchange-role-permissions"></a>
Core device roles don't allow access to S3 buckets by default. If this is your first time using this S3 bucket, you must add permissions to the role to allow core devices to retrieve component artifacts from this S3 bucket. For more information, see [Allow access to S3 buckets for component artifacts](device-service-role.md#device-service-role-access-s3-bucket).

**To publish a Greengrass component (GDK CLI)**

1. Open the component folder in a command prompt or terminal.

1. If you haven't already, build the Greengrass component. The [component build](greengrass-development-kit-cli-component.md#greengrass-development-kit-cli-component-build) command produces a recipe and artifacts in the `greengrass-build` folder in the component folder. Run the following command.

   ```
   gdk component build
   ```

1. Publish the component to the AWS Cloud. The [component publish](greengrass-development-kit-cli-component.md#greengrass-development-kit-cli-component-publish) command uploads the component's artifacts to Amazon S3 and updates the component's recipe with each artifact's URI. Then, it creates the component in the AWS IoT Greengrass service.
**Note**  <a name="publish-component-s3-bucket-artifact-digest-warning"></a>
AWS IoT Greengrass computes the digest of each artifact when you create the component. This means that you can't modify the artifact files in your S3 bucket after you create a component. If you do, deployments that include this component will fail, because the file digest doesn't match. If you modify an artifact file, you must create a new version of the component.

   If you specify `NEXT_PATCH` for the component version in the GDK CLI configuration file, the GDK CLI uses the next patch version that doesn't already exist in the AWS IoT Greengrass service.

   Run the following command.

   ```
   gdk component publish
   ```

   The output tells you the version of the component that the GDK CLI created.

   After you publish the component, you can deploy the component to core devices. For more information, see [Deploy AWS IoT Greengrass components to devices](manage-deployments.md).

## Publish a component (shell commands)


Use the following procedure to publish a component using shell commands and the AWS Command Line Interface (AWS CLI). When you publish a component, you do the following:

1. Publish component artifacts to an S3 bucket.

1. Add each artifact's Amazon S3 URI to the component recipe.

1. Create a component version in AWS IoT Greengrass from the component recipe.

**Note**  <a name="component-version-uniqueness-note"></a>
<a name="component-version-uniqueness-para"></a>Each component version that you upload must be unique. Make sure that you upload the correct component version, because you can't edit it after you upload it.

You can follow these steps to publish a component from your development computer or your Greengrass core device.

**To publish a component (shell commands)**

1. If the component uses a version that exists in the AWS IoT Greengrass service, then you must change the version of the component. Open the recipe in a text editor, increment the version, and save the file. Choose a new version that reflects the changes that you made to the component.
**Note**  <a name="semver-note"></a>
<a name="semver-para"></a>AWS IoT Greengrass uses semantic versions for components. Semantic versions follow a *major*.*minor*.*patch* number system. For example, version `1.0.0` represents the first major release for a component. For more information, see the [semantic version specification](https://semver.org/).

1. If your component has artifacts, do the following:

   1. Publish the component's artifacts to an S3 bucket in your AWS account.
**Tip**  <a name="artifact-path-tip"></a>
We recommend that you include the component name and version in the path to the artifact in the S3 bucket. This naming scheme can help you maintain the artifacts that previous versions of the component use, so you can continue to support previous component versions.

      Run the following command to publish an artifact file to an S3 bucket. Replace amzn-s3-demo-bucket with the name of the bucket, and replace *artifacts/com.example.HelloWorld/1.0.0/artifact.py* with the path to the artifact file.

      ```
      aws s3 cp artifacts/com.example.HelloWorld/1.0.0/artifact.py s3://amzn-s3-demo-bucket/artifacts/com.example.HelloWorld/1.0.0/artifact.py
      ```
**Important**  <a name="publish-component-s3-bucket-token-exchange-role-permissions"></a>
Core device roles don't allow access to S3 buckets by default. If this is your first time using this S3 bucket, you must add permissions to the role to allow core devices to retrieve component artifacts from this S3 bucket. For more information, see [Allow access to S3 buckets for component artifacts](device-service-role.md#device-service-role-access-s3-bucket).

   1. Add a list named `Artifacts` to the component recipe if it isn't present. The `Artifacts` list appears in each manifest, which defines the component's requirements on each platform that it supports (or the component's default requirements for all platforms).

   1. Add each artifact to the list of artifacts, or update the URI of existing artifacts. The Amazon S3 URI is composed of the bucket name and the path to the artifact object in the bucket. Your artifacts' Amazon S3 URIs should look similar to the following example.

      ```
      s3://amzn-s3-demo-bucket/artifacts/com.example.HelloWorld/1.0.0/artifact.py
      ```

   After you complete these steps, your recipe should have an `Artifacts` list that looks like the following.

------
#### [ JSON ]

   ```
   {
     ...
     "Manifests": [
       {
         "Lifecycle": {
           ...
         },
         "Artifacts": [
           {
             "URI": "s3://amzn-s3-demo-bucket/artifacts/MyGreengrassComponent/1.0.0/artifact.py",
             "Unarchive": "NONE"
           }
         ]
       }
     ]
   }
   ```

**Note**  
You can add the `"Unarchive": "ZIP"` option for a ZIP artifact to configure the AWS IoT Greengrass Core software to unzip the artifact when the component deploys.

------
#### [ YAML ]

   ```
   ...
   Manifests:
     - Lifecycle:
         ...
       Artifacts:
         - URI: s3://amzn-s3-demo-bucket/artifacts/MyGreengrassComponent/1.0.0/artifact.py
           Unarchive: NONE
   ```

**Note**  
You can use the `Unarchive: ZIP` option to configure the AWS IoT Greengrass Core software to unzip a ZIP artifact when the component deploys. For more information about how to use ZIP artifacts in a component, see the [artifacts:decompressedPath recipe variable](component-recipe-reference.md#component-recipe-artifacts-decompressed-path).

------

   For more information about recipes, see [AWS IoT Greengrass component recipe reference](component-recipe-reference.md).

1. Use the AWS IoT Greengrass console to create a component from the recipe file.

   Run the following command to create the component from a recipe file. This command creates the component and publishes it as a private AWS IoT Greengrass component in your AWS account. Replace *path/to/recipeFile* with the path to the recipe file.

   ```
   aws greengrassv2 create-component-version --inline-recipe fileb://path/to/recipeFile
   ```

   Copy the `arn` from the response to check the state of the component in the next step.
**Note**  <a name="publish-component-s3-bucket-artifact-digest-warning"></a>
AWS IoT Greengrass computes the digest of each artifact when you create the component. This means that you can't modify the artifact files in your S3 bucket after you create a component. If you do, deployments that include this component will fail, because the file digest doesn't match. If you modify an artifact file, you must create a new version of the component.

1. Each component in the AWS IoT Greengrass service has a state. Run the following command to confirm the state of the component version that you publish in this procedure. Replace *com.example.HelloWorld* and *1.0.0* with the component version to query. Replace the `arn` with the ARN from the previous step.

   ```
   aws greengrassv2 describe-component --arn "arn:aws:greengrass:region:account-id:components:com.example.HelloWorld:versions:1.0.0"
   ```

   The operation returns a response that contains the component's metadata. The metadata contains a `status` object that contains the component state and any errors, if applicable.

   When the component state is `DEPLOYABLE`, you can deploy the component to devices. For more information, see [Deploy AWS IoT Greengrass components to devices](manage-deployments.md).

# Interact with AWS services


Greengrass core devices use X.509 certificates to connect to AWS IoT Core using TLS mutual authentication protocols. These certificates let devices interact with AWS IoT without AWS credentials, which typically comprise an access key ID and a secret access key. Other AWS services require AWS credentials instead of X.509 certificates to call API operations at service endpoints. AWS IoT Core has a credentials provider that enables devices to use their X.509 certificate to authenticate AWS requests. The AWS IoT credentials provider authenticates devices using an X.509 certificate and issues AWS credentials in the form a temporary, limited-privilege security token. Devices can use this token to sign and authenticate any AWS request. This eliminates the need to store AWS credentials on 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*.

To fetch credentials from AWS IoT, Greengrass, core devices use an AWS IoT role alias that points to an IAM role. This IAM role is called the *token exchange role*. You create the role alias and token exchange role when you install the AWS IoT Greengrass Core software. To specify the role alias that a core device uses, configure the `iotRoleAlias` parameter of the [Greengrass nucleus](greengrass-nucleus-component.md).

The AWS IoT credentials provider assumes the token exchange role on your behalf to provide AWS credentials to core devices. You can attach appropriate IAM policies to this role to allow your core devices access to your AWS resources, such as components artifacts in S3 buckets. For more information about how to configure the token exchange role, see [Authorize core devices to interact with AWS services](device-service-role.md).

Greengrass core devices store AWS credentials in memory, and the credentials expire after an hour by default. If the AWS IoT Greengrass Core software restarts, it must fetch credentials again. You can use the [UpdateRoleAlias](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateRoleAlias.html) operation to configure the duration that credentials are valid.

AWS IoT Greengrass provides a public component, the token exchange service component, that you can define as a dependency in your custom component to interact with AWS services. The token exchange service provides your component with an environment variable, `AWS_CONTAINER_CREDENTIALS_FULL_URI`, that defines the URI to a local server that provides AWS credentials. When you create an AWS SDK client, the client checks for this environment variable and connects to the local server to retrieve AWS credentials and uses them to sign API requests. This lets you use AWS SDKs and other tools to call AWS services in your components. For more information, see [Token exchange service](token-exchange-service-component.md).

**Important**  <a name="token-exchange-service-aws-sdk-requirement"></a>
Support to acquire AWS credentials in this way was added to the AWS SDKs on July 13th, 2016. Your component must use an AWS SDK version that was created on or after that date. For more information, see [Using a supported AWS SDK](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html#task-iam-roles-minimum-sdk) in the *Amazon Elastic Container Service Developer Guide*.

To acquire AWS credentials in your custom component, define `aws.greengrass.TokenExchangeService` as a dependency in the component recipe. The following example recipe defines a component that installs [boto3](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html) and runs a Python script that uses AWS credentials from the token exchange service to list Amazon S3 buckets.

**Note**  
To run this example component, your device must have the `s3:ListAllMyBuckets` permission. For more information, see [Authorize core devices to interact with AWS services](device-service-role.md).

------
#### [ JSON ]

```
{
  "RecipeFormatVersion": "2020-01-25",
  "ComponentName": "com.example.ListS3Buckets",
  "ComponentVersion": "1.0.0",
  "ComponentDescription": "A component that uses the token exchange service to list S3 buckets.",
  "ComponentPublisher": "Amazon",
  "ComponentDependencies": {
    "aws.greengrass.TokenExchangeService": {
      "VersionRequirement": "^2.0.0",
      "DependencyType": "HARD"
    }
  },
  "Manifests": [
    {
      "Platform": {
        "os": "linux"
      },
      "Lifecycle": {
        "install": "pip3 install --user boto3",
        "Run": "python3 -u {artifacts:path}/list_s3_buckets.py"
      }
    },
    {
      "Platform": {
        "os": "windows"
      },
      "Lifecycle": {
        "install": "pip3 install --user boto3",
        "Run": "py -3 -u {artifacts:path}/list_s3_buckets.py"
      }
    }
  ]
}
```

------
#### [ YAML ]

```
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.ListS3Buckets
ComponentVersion: '1.0.0'
ComponentDescription: A component that uses the token exchange service to list S3 buckets.
ComponentPublisher: Amazon
ComponentDependencies:
  aws.greengrass.TokenExchangeService:
    VersionRequirement: '^2.0.0'
    DependencyType: HARD
Manifests:
  - Platform:
      os: linux
    Lifecycle:
      install:
        pip3 install --user boto3
      Run: |-
        python3 -u {artifacts:path}/list_s3_buckets.py
  - Platform:
      os: windows
    Lifecycle:
      install:
        pip3 install --user boto3
      Run: |-
        py -3 -u {artifacts:path}/list_s3_buckets.py
```

------

This example component runs the following Python script, `list_s3_buckets.py` that lists Amazon S3 buckets.

```
import boto3
import os

try:
    print("Creating boto3 S3 client...")
    s3 = boto3.client('s3')
    print("Successfully created boto3 S3 client")
except Exception as e:
    print("Failed to create boto3 s3 client. Error: " + str(e))
    exit(1)

try:
    print("Listing S3 buckets...")
    response = s3.list_buckets()
    for bucket in response['Buckets']:
        print(f'\t{bucket["Name"]}')
    print("Successfully listed S3 buckets")
except Exception as e:
    print("Failed to list S3 buckets. Error: " + str(e))
    exit(1)
```

# Run a Docker container


You can configure AWS IoT Greengrass components to run a [Docker](https://www.docker.com/) container from images stored in the following locations:
+ Public and private image repositories in Amazon Elastic Container Registry (Amazon ECR)
+ Public Docker Hub repository
+ Public Docker Trusted Registry
+ S3 bucket

In your custom component, include the Docker image URI as an artifact to retrieve the image and run it on the core device. For Amazon ECR and Docker Hub images, you can use the [Docker application manager](docker-application-manager-component.md) component to download the images and manage credentials for private Amazon ECR repositories.

**Topics**
+ [

## Requirements
](#run-docker-container-requirements)
+ [

## Run a Docker container from a public image in Amazon ECR or Docker Hub
](#run-docker-container-public-ecr-dockerhub)
+ [

## Run a Docker container from a private image in Amazon ECR
](#run-docker-container-private-ecr)
+ [

## Run a Docker container from an image in Amazon S3
](#run-docker-container-s3)
+ [

## Use interprocess communication in Docker container components
](#docker-container-ipc)
+ [

## Use AWS credentials in Docker container components (Linux)
](#docker-container-token-exchange-service)
+ [

## Use stream manager in Docker container components (Linux)
](#docker-container-stream-manager)

## Requirements


To run a Docker container in a component, you need the following:
+ A Greengrass core device. If you don't have one, see [Tutorial: Getting started with AWS IoT Greengrass V2](getting-started.md).
+ <a name="docker-engine-requirement"></a>[Docker Engine](https://docs.docker.com/engine/) 1.9.1 or later installed on the Greengrass core device. Version 20.10 is the latest version that is verified to work with the AWS IoT Greengrass Core software. You must install Docker directly on the core device before you deploy components that run Docker containers.
**Tip**  
You can also configure the core device to install Docker Engine when the component installs. For example, the following install script installs Docker Engine before it loads the Docker image. This install script works on Debian-based Linux distributions, such as Ubuntu. If you configure the component to install Docker Engine with this command, you may need to set `RequiresPrivilege` to `true` in the lifecycle script to run the installation and `docker` commands. For more information, see [AWS IoT Greengrass component recipe reference](component-recipe-reference.md).  

  ```
  apt-get install docker-ce docker-ce-cli containerd.io && docker load -i {artifacts:path}/hello-world.tar
  ```
+ <a name="docker-user-permissions-requirement"></a>The system user that runs a Docker container component must have root or administrator permissions, or you must configure Docker to run it as a non-root or non-admistrator user.
  + On Linux devices, you can add a user to the `docker` group to call `docker` commands without `sudo`.
  + On Windows devices, you can add a user to the `docker-users` group to call `docker` commands without adminstrator privileges.

------
#### [ Linux or Unix ]

  To add `ggc_user`, or the non-root user that you use to run Docker container components, to the `docker` group, run the following command.

  ```
  sudo usermod -aG docker ggc_user
  ```

  For more information, see [Manage Docker as a non-root user](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user).

------
#### [ Windows Command Prompt (CMD) ]

  To add `ggc_user`, or the user that you use to run Docker container components, to the `docker-users` group, run the following command as an administrator.

  ```
  net localgroup docker-users ggc_user /add
  ```

------
#### [ Windows PowerShell ]

  To add `ggc_user`, or the user that you use to run Docker container components, to the `docker-users` group, run the following command as an administrator.

  ```
  Add-LocalGroupMember -Group docker-users -Member ggc_user
  ```

------
+ Files accessed by the Docker container component [mounted as a volume](https://docs.docker.com/storage/volumes/) in the Docker container.
+ <a name="docker-proxy-requirement"></a>If you [configure the AWS IoT Greengrass Core software to use a network proxy](configure-greengrass-core-v2.md#configure-alpn-network-proxy), you must [configure Docker to use the same proxy server](https://docs.docker.com/network/proxy/).

In addition to these requirements, you must also meet the following requirements if they apply to your environment:
+ To use [Docker Compose](https://docs.docker.com/compose/) to create and start your Docker containers, install Docker Compose on your Greengrass core device, and upload your Docker Compose file to an S3 bucket. You must store your Compose file in an S3 bucket in the same AWS account and AWS Region as the component. For an example that uses the `docker-compose up` command in a custom component, see [Run a Docker container from a public image in Amazon ECR or Docker Hub](#run-docker-container-public-ecr-dockerhub).
+ If you run AWS IoT Greengrass behind a network proxy, configure the Docker daemon to use a [proxy server](https://docs.docker.com/network/proxy/). 
+ If your Docker images are stored in Amazon ECR or Docker Hub, include the [Docker component manager](docker-application-manager-component.md) component as a dependency in your Docker container component. You must start the Docker daemon on the core device before you deploy your component. 

  Also, include the image URIs as component artifacts. Image URIs must be in the format `docker:registry/image[:tag|@digest]` as shown in the following examples:<a name="docker-image-artifact-uri"></a>
  + Private Amazon ECR image: `docker:account-id.dkr.ecr.region.amazonaws.com/repository/image[:tag|@digest]`
  + Public Amazon ECR image: `docker:public.ecr.aws/repository/image[:tag|@digest]`
  + Public Docker Hub image: `docker:name[:tag|@digest]`

  For more information about running Docker containers from images stored in public repositories, see [Run a Docker container from a public image in Amazon ECR or Docker Hub](#run-docker-container-public-ecr-dockerhub).
+ If your Docker images are stored in an Amazon ECR private repository, then you must include the token exchange service component as a dependency in the Docker container component. Also, the [Greengrass device role](device-service-role.md) must allow the `ecr:GetAuthorizationToken`, `ecr:BatchGetImage`, and `ecr:GetDownloadUrlForLayer` actions, as shown in the following example IAM policy. 

------
#### [ JSON ]

****  

  ```
  {
    "Version":"2012-10-17",		 	 	 
    "Statement": [
      {
        "Action": [
          "ecr:GetAuthorizationToken",
          "ecr:BatchGetImage",
          "ecr:GetDownloadUrlForLayer"
        ],
        "Resource": [
          "*"
        ],
        "Effect": "Allow"
      }
    ]
  }
  ```

------

  For information about running Docker containers from images stored in an Amazon ECR private repository, see [Run a Docker container from a private image in Amazon ECR](#run-docker-container-private-ecr).
+ To use Docker images stored in an Amazon ECR private repository, the private repository must be in the same AWS Region as the core device.
+ If your Docker images or Compose files are stored in an S3 bucket, the [Greengrass device role](device-service-role.md) must allow the `s3:GetObject` permission to allow core devices to download the images as component artifacts, as shown in the following example IAM policy. 

------
#### [ JSON ]

****  

  ```
  {
    "Version":"2012-10-17",		 	 	 
    "Statement": [
      {
        "Action": [
          "s3:GetObject"
        ],
        "Resource": [
          "*"
        ],
        "Effect": "Allow"
      }
    ]
  }
  ```

------

  For information about running Docker containers from images stored in Amazon S3, see [Run a Docker container from an image in Amazon S3](#run-docker-container-s3).
+ <a name="docker-greengrass-features-requirements"></a>To use interprocess communication (IPC), AWS credentials, or stream manager in your Docker container component, you must specify additional options when you run the Docker container. For more information, see the following:<a name="docker-greengrass-features-requirements-links"></a>
  + [Use interprocess communication in Docker container components](#docker-container-ipc)
  + [Use AWS credentials in Docker container components (Linux)](#docker-container-token-exchange-service)
  + [Use stream manager in Docker container components (Linux)](#docker-container-stream-manager)

## Run a Docker container from a public image in Amazon ECR or Docker Hub


This section describes how you can create a custom component that uses Docker Compose to run a Docker container from Docker images that are stored Amazon ECR and Docker Hub.

**To run a Docker container using Docker Compose**

1. Create and upload a Docker Compose file to an Amazon S3 bucket. Make sure that the [Greengrass device role](device-service-role.md) allows the `s3:GetObject` permission to enable the device to access the Compose file. The example Compose file shown in the following example includes the Amazon CloudWatch Agent image from Amazon ECR and the MySQL image from Docker Hub.

   ```
   version: "3"
   services:
     cloudwatchagent:
       image: "public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest"
     mysql:
       image: "mysql:8.0"
   ```

1. [Create a custom component](create-components.md) on your AWS IoT Greengrass core device. The example recipe shown in the following example has the following properties:
   + The Docker application manager component as a dependency. This component enables AWS IoT Greengrass to download images from public Amazon ECR and Docker Hub repositories.
   + A component artifact that specifies a Docker image in a public Amazon ECR repository.
   + A component artifact that specifies a Docker image in a public Docker Hub repository.
   + A component artifact that specifies the Docker Compose file that includes containers for the Docker images that you want to run. 
   + A lifecycle run script that uses [docker-compose up](https://docs.docker.com/compose/reference/up/) to create and start a container from the specified images.

------
#### [ JSON ]

   ```
   {
     "RecipeFormatVersion": "2020-01-25",
     "ComponentName": "com.example.MyDockerComposeComponent",
     "ComponentVersion": "1.0.0",
     "ComponentDescription": "A component that uses Docker Compose to run images from public Amazon ECR and Docker Hub.",
     "ComponentPublisher": "Amazon",
     "ComponentDependencies": {
       "aws.greengrass.DockerApplicationManager": {
         "VersionRequirement": "~2.0.0"
       }
     },
     "Manifests": [
       {
         "Platform": {
           "os": "all"
         },
         "Lifecycle": {
           "Run": "docker-compose -f {artifacts:path}/docker-compose.yaml up"
         },
         "Artifacts": [
           {
             "URI": "docker:public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest"
           },
           {
             "URI": "docker:mysql:8.0"
           },
           {
             "URI": "s3://amzn-s3-demo-bucket/folder/docker-compose.yaml"
           }
         ]
       }
     ]
   }
   ```

------
#### [ YAML ]

   ```
   ---
   RecipeFormatVersion: '2020-01-25'
   ComponentName: com.example.MyDockerComposeComponent
   ComponentVersion: '1.0.0'
   ComponentDescription: 'A component that uses Docker Compose to run images from public Amazon ECR and Docker Hub.'
   ComponentPublisher: Amazon
   ComponentDependencies:
     aws.greengrass.DockerApplicationManager:
       VersionRequirement: ~2.0.0
   Manifests:
     - Platform:
         os: all
       Lifecycle:
           Run: docker-compose -f {artifacts:path}/docker-compose.yaml up
       Artifacts:
         - URI: "docker:public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest"
         - URI: "docker:mysql:8.0"
         - URI: "s3://amzn-s3-demo-bucket/folder/docker-compose.yaml"
   ```

------
**Note**  
<a name="docker-greengrass-features-requirements"></a>To use interprocess communication (IPC), AWS credentials, or stream manager in your Docker container component, you must specify additional options when you run the Docker container. For more information, see the following:  
[Use interprocess communication in Docker container components](#docker-container-ipc)
[Use AWS credentials in Docker container components (Linux)](#docker-container-token-exchange-service)
[Use stream manager in Docker container components (Linux)](#docker-container-stream-manager)

1. [Test the component](test-components.md) to verify that it works as expected.
**Important**  
You must install and start the Docker daemon before you deploy the component.

   After you deploy the component locally, you can run the [docker container ls](https://docs.docker.com/engine/reference/commandline/container_ls/) command to verify that your container runs.

   ```
   docker container ls
   ```

1. When the component is ready, upload the component to AWS IoT Greengrass to deploy to other core devices. For more information, see [Publish components to deploy to your core devices](publish-components.md).

## Run a Docker container from a private image in Amazon ECR


This section describes how you can create a custom component that runs a Docker container from a Docker image that is stored in a private repository in Amazon ECR.

**To run a Docker container**

1. [Create a custom component](create-components.md) on your AWS IoT Greengrass core device. Use the following example recipe, which has the following properties:
   + The Docker application manager component as a dependency. This component enables AWS IoT Greengrass to manage credentials to download images from private repositories.
   + The token exchange service component as a dependency. This component enables AWS IoT Greengrass to retrieve AWS credentials to interact with Amazon ECR.
   + A component artifact that specifies a Docker image in a private Amazon ECR repository.
   + A lifecycle run script that uses [docker run](https://docs.docker.com/engine/reference/commandline/run/) to create and start a container from the image.

------
#### [ JSON ]

   ```
   {
     "RecipeFormatVersion": "2020-01-25",
     "ComponentName": "com.example.MyPrivateDockerComponent",
     "ComponentVersion": "1.0.0",
     "ComponentDescription": "A component that runs a Docker container from a private Amazon ECR image.",
     "ComponentPublisher": "Amazon",
     "ComponentDependencies": {
       "aws.greengrass.DockerApplicationManager": {
         "VersionRequirement": "~2.0.0"
       },
       "aws.greengrass.TokenExchangeService": {
         "VersionRequirement": "~2.0.0"
       }
     },
     "Manifests": [
       {
         "Platform": {
           "os": "all"
         },
         "Lifecycle": {
           "Run": "docker run account-id.dkr.ecr.region.amazonaws.com/repository[:tag|@digest]"
         },
         "Artifacts": [
           {
             "URI": "docker:account-id.dkr.ecr.region.amazonaws.com/repository[:tag|@digest]"
           }
         ]
       }
     ]
   }
   ```

------
#### [ YAML ]

   ```
   ---
   RecipeFormatVersion: '2020-01-25'
   ComponentName: com.example.MyPrivateDockerComponent
   ComponentVersion: '1.0.0'
   ComponentDescription: 'A component that runs a Docker container from a private Amazon ECR image.'
   ComponentPublisher: Amazon
   ComponentDependencies:
     aws.greengrass.DockerApplicationManager:
       VersionRequirement: ~2.0.0
     aws.greengrass.TokenExchangeService:
       VersionRequirement: ~2.0.0
   Manifests:
     - Platform:
         os: all
       Lifecycle:
           Run: docker run account-id.dkr.ecr.region.amazonaws.com/repository[:tag|@digest]
       Artifacts:
         - URI: "docker:account-id.dkr.ecr.region.amazonaws.com/repository[:tag|@digest]"
   ```

------
**Note**  
<a name="docker-greengrass-features-requirements"></a>To use interprocess communication (IPC), AWS credentials, or stream manager in your Docker container component, you must specify additional options when you run the Docker container. For more information, see the following:  
[Use interprocess communication in Docker container components](#docker-container-ipc)
[Use AWS credentials in Docker container components (Linux)](#docker-container-token-exchange-service)
[Use stream manager in Docker container components (Linux)](#docker-container-stream-manager)

1. [Test the component](test-components.md) to verify that it works as expected.
**Important**  
You must install and start the Docker daemon before you deploy the component.

   After you deploy the component locally, you can run the [docker container ls](https://docs.docker.com/engine/reference/commandline/container_ls/) command to verify that your container runs.

   ```
   docker container ls
   ```

1. Upload the component to AWS IoT Greengrass to deploy to other core devices. For more information, see [Publish components to deploy to your core devices](publish-components.md).

## Run a Docker container from an image in Amazon S3


This section describes how you can run a Docker container in a component from a Docker image that is stored in Amazon S3.

**To run a Docker container in a component from an image in Amazon S3**

1. Run the [docker save](https://docs.docker.com/engine/reference/commandline/save/) command to create a backup of a Docker container. You provide this backup as a component artifact to run the container on AWS IoT Greengrass. Replace *hello-world* with the name of the image, and replace *hello-world.tar* with the name of the archive file to create.

   ```
   docker save hello-world > artifacts/com.example.MyDockerComponent/1.0.0/hello-world.tar
   ```

1. [Create a custom component](create-components.md) on your AWS IoT Greengrass core device. Use the following example recipe, which has the following properties:
   + A lifecycle install script that uses [docker load](https://docs.docker.com/engine/reference/commandline/load/) to load a Docker image from an archive.
   + A lifecycle run script that uses [docker run](https://docs.docker.com/engine/reference/commandline/run/) to create and start a container from the image. The `--rm` option cleans up the container when it exits.

------
#### [ JSON ]

   ```
   {
     "RecipeFormatVersion": "2020-01-25",
     "ComponentName": "com.example.MyS3DockerComponent",
     "ComponentVersion": "1.0.0",
     "ComponentDescription": "A component that runs a Docker container from an image in an S3 bucket.",
     "ComponentPublisher": "Amazon",
     "Manifests": [
       {
         "Platform": {
           "os": "linux"
         },
         "Lifecycle": {
           "install": {
             "Script": "docker load -i {artifacts:path}/hello-world.tar"
           },
           "Run": {
             "Script": "docker run --rm hello-world"
           }
         }
       }
     ]
   }
   ```

------
#### [ YAML ]

   ```
   ---
   RecipeFormatVersion: '2020-01-25'
   ComponentName: com.example.MyS3DockerComponent
   ComponentVersion: '1.0.0'
   ComponentDescription: 'A component that runs a Docker container from an image in an S3 bucket.'
   ComponentPublisher: Amazon
   Manifests:
     - Platform:
         os: linux
       Lifecycle:
         install:
           Script: docker load -i {artifacts:path}/hello-world.tar
         Run:
           Script: docker run --rm hello-world
   ```

------
**Note**  
<a name="docker-greengrass-features-requirements"></a>To use interprocess communication (IPC), AWS credentials, or stream manager in your Docker container component, you must specify additional options when you run the Docker container. For more information, see the following:  
[Use interprocess communication in Docker container components](#docker-container-ipc)
[Use AWS credentials in Docker container components (Linux)](#docker-container-token-exchange-service)
[Use stream manager in Docker container components (Linux)](#docker-container-stream-manager)

1. [Test the component](test-components.md) to verify that it works as expected.

   After you deploy the component locally, you can run the [docker container ls](https://docs.docker.com/engine/reference/commandline/container_ls/) command to verify that your container runs.

   ```
   docker container ls
   ```

1. When the component is ready, upload the Docker image archive to an S3 bucket, and add its URI to the component recipe. Then, you can upload the component to AWS IoT Greengrass to deploy to other core devices. For more information, see [Publish components to deploy to your core devices](publish-components.md).

   When you're done, the component recipe should look like the following example.

------
#### [ JSON ]

   ```
   {
     "RecipeFormatVersion": "2020-01-25",
     "ComponentName": "com.example.MyS3DockerComponent",
     "ComponentVersion": "1.0.0",
     "ComponentDescription": "A component that runs a Docker container from an image in an S3 bucket.",
     "ComponentPublisher": "Amazon",
     "Manifests": [
       {
         "Platform": {
           "os": "linux"
         },
         "Lifecycle": {
           "install": {
             "Script": "docker load -i {artifacts:path}/hello-world.tar"
           },
           "Run": {
             "Script": "docker run --rm hello-world"
           }
         },
         "Artifacts": [
           {
             "URI": "s3://amzn-s3-demo-bucket/artifacts/com.example.MyDockerComponent/1.0.0/hello-world.tar"
           }
         ]
       }
     ]
   }
   ```

------
#### [ YAML ]

   ```
   ---
   RecipeFormatVersion: '2020-01-25'
   ComponentName: com.example.MyS3DockerComponent
   ComponentVersion: '1.0.0'
   ComponentDescription: 'A component that runs a Docker container from an image in an S3 bucket.'
   ComponentPublisher: Amazon
   Manifests:
     - Platform:
         os: linux
       Lifecycle:
         install:
           Script: docker load -i {artifacts:path}/hello-world.tar
         Run:
           Script: docker run --rm hello-world
       Artifacts:
         - URI: s3://amzn-s3-demo-bucket/artifacts/com.example.MyDockerComponent/1.0.0/hello-world.tar
   ```

------

## Use interprocess communication in Docker container components


You can use the Greengrass interprocess communication (IPC) library in the AWS IoT Device SDK or the AWS IoT Greengrass Component SDK to communicate with the Greengrass nucleus, other Greengrass components, and AWS IoT Core. For more information, see [Use the AWS IoT Device SDK to communicate with the Greengrass nucleus, other components, and AWS IoT CoreCommunicate with the Greengrass nucleus, other components, and AWS IoT Core](interprocess-communication.md).

To use IPC in a Docker container component, you must run the Docker container with the following parameters:
+ Mount the IPC socket in the container. The Greengrass nucleus provides the IPC socket file path in the `AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT` environment variable.
+ Set the `SVCUID` and `AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT` environment variables to the values that the Greengrass nucleus provides to components. Your component uses these environment variables to authenticate connections to the Greengrass nucleus.

**Example recipe: Publish an MQTT message to AWS IoT Core (Python)**  
The following recipe defines an example Docker container component that publishes an MQTT message to AWS IoT Core. This recipe has the following properties:  
+ An authorization policy (`accessControl`) that allows the component to publish MQTT messages to AWS IoT Core on all topics. For more information, see [Authorize components to perform IPC operations](interprocess-communication.md#ipc-authorization-policies) and [AWS IoT Core MQTT IPC authorization](ipc-iot-core-mqtt.md#ipc-iot-core-mqtt-authorization).
+ A component artifact that specifies a Docker image as a TAR archive in Amazon S3.
+ A lifecycle install script that loads the Docker image from the TAR archive.
+ A lifecycle run script that runs a Docker container from the image. The [Docker run](https://docs.docker.com/engine/reference/run/) command has the following arguments:
  + The `-v` argument mounts the Greengrass IPC socket in the container.
  + The first two `-e` arguments set the required environment variables in the Docker container.
  + The additional `-e` arguments set environment variables used by this example.
  + The `--rm` argument cleans up the container when it exits.

```
{
  "RecipeFormatVersion": "2020-01-25",
  "ComponentName": "com.example.python.docker.PublishToIoTCore",
  "ComponentVersion": "1.0.0",
  "ComponentDescription": "Uses interprocess communication to publish an MQTT message to IoT Core.",
  "ComponentPublisher": "Amazon",
  "ComponentConfiguration": {
    "DefaultConfiguration": {
      "topic": "test/topic/java",
      "message": "Hello, World!",
      "qos": "1",
      "accessControl": {
        "aws.greengrass.ipc.mqttproxy": {
          "com.example.python.docker.PublishToIoTCore:pubsub:1": {
            "policyDescription": "Allows access to publish to IoT Core on all topics.",
            "operations": [
              "aws.greengrass#PublishToIoTCore"
            ],
            "resources": [
              "*"
            ]
          }
        }
      }
    }
  },
  "Manifests": [
    {
      "Platform": {
        "os": "all"
      },
      "Lifecycle": {
        "install": "docker load -i {artifacts:path}/publish-to-iot-core.tar",
        "Run": "docker run -v $AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT:$AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT -e SVCUID -e AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT -e MQTT_TOPIC=\"{configuration:/topic}\" -e MQTT_MESSAGE=\"{configuration:/message}\" -e MQTT_QOS=\"{configuration:/qos}\" --rm publish-to-iot-core"
      },
      "Artifacts": [
        {
          "URI": "s3://amzn-s3-demo-bucket/artifacts/com.example.python.docker.PublishToIoTCore/1.0.0/publish-to-iot-core.tar"
        }
      ]
    }
  ]
}
```

```
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.python.docker.PublishToIoTCore
ComponentVersion: 1.0.0
ComponentDescription: Uses interprocess communication to publish an MQTT message to IoT Core.
ComponentPublisher: Amazon
ComponentConfiguration:
  DefaultConfiguration:
    topic: 'test/topic/java'
    message: 'Hello, World!'
    qos: '1'
    accessControl:
      aws.greengrass.ipc.mqttproxy:
        'com.example.python.docker.PublishToIoTCore:pubsub:1':
          policyDescription: Allows access to publish to IoT Core on all topics.
          operations:
            - 'aws.greengrass#PublishToIoTCore'
          resources:
            - '*'
Manifests:
  - Platform:
      os: all
    Lifecycle:
      install: 'docker load -i {artifacts:path}/publish-to-iot-core.tar'
      Run: |
        docker run \
          -v $AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT:$AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT \
          -e SVCUID \
          -e AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT \
          -e MQTT_TOPIC="{configuration:/topic}" \
          -e MQTT_MESSAGE="{configuration:/message}" \
          -e MQTT_QOS="{configuration:/qos}" \
          --rm publish-to-iot-core
    Artifacts:
      - URI: s3://amzn-s3-demo-bucket/artifacts/com.example.python.docker.PublishToIoTCore/1.0.0/publish-to-iot-core.tar
```

## Use AWS credentials in Docker container components (Linux)


You can use the [token exchange service component](token-exchange-service-component.md) to interact with AWS services in Greengrass components. This component provides AWS credentials from the core device's [token exchange role](device-service-role.md) using a local container server. For more information, see [Interact with AWS services](interact-with-aws-services.md).

**Note**  
The example in this section works only on Linux core devices.

To use AWS credentials from the token exchange service in a Docker container component, you must run the Docker container with the following parameters:
+ Provide access to the host network using the `--network=host` argument. This option enables the Docker container to connect to the local token exchange service to retrieve AWS credentials. This argument works on only Docker for Linux.
**Warning**  <a name="docker-network-host-security-warning"></a>
This option gives the container access to all local network interfaces on the host, so this option is less secure than if you run Docker containers without this access to the host network. Consider this when you develop and run Docker container components that use this option. For more information, see [Network: host](https://docs.docker.com/engine/reference/run/#network-host) in the *Docker Documentation*.
+ Set the `AWS_CONTAINER_CREDENTIALS_FULL_URI` and `AWS_CONTAINER_AUTHORIZATION_TOKEN` environment variables to the values that the Greengrass nucleus provides to components. AWS SDKs use these environment variables to retrieve AWS credentials.

**Example recipe: List S3 buckets in a Docker container component (Python)**  
The following recipe defines an example Docker container component that lists the S3 buckets in your AWS account. This recipe has the following properties:  
+ The token exchange service component as a dependency. This dependency enables the component to retrieve AWS credentials to interact with other AWS services.
+ A component artifact that specifies a Docker image as a tar archive in Amazon S3.
+ A lifecycle install script that loads the Docker image from the TAR archive.
+ A lifecycle run script that runs a Docker container from the image. The [Docker run](https://docs.docker.com/engine/reference/run/) command has the following arguments:
  + The `--network=host` argument provides the container access to the host network, so the container can connect to the token exchange service.
  + The `-e` argument sets the required environment variables in the Docker container.
  + The `--rm` argument cleans up the container when it exits.

```
{
  "RecipeFormatVersion": "2020-01-25",
  "ComponentName": "com.example.python.docker.ListS3Buckets",
  "ComponentVersion": "1.0.0",
  "ComponentDescription": "Uses the token exchange service to lists your S3 buckets.",
  "ComponentPublisher": "Amazon",
  "ComponentDependencies": {
    "aws.greengrass.TokenExchangeService": {
      "VersionRequirement": "^2.0.0",
      "DependencyType": "HARD"
    }
  },
  "Manifests": [
    {
      "Platform": {
        "os": "linux"
      },
      "Lifecycle": {
        "install": "docker load -i {artifacts:path}/list-s3-buckets.tar",
        "Run": "docker run --network=host -e AWS_CONTAINER_AUTHORIZATION_TOKEN -e AWS_CONTAINER_CREDENTIALS_FULL_URI --rm list-s3-buckets"
      },
      "Artifacts": [
        {
          "URI": "s3://amzn-s3-demo-bucket/artifacts/com.example.python.docker.ListS3Buckets/1.0.0/list-s3-buckets.tar"
        }
      ]
    }
  ]
}
```

```
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.python.docker.ListS3Buckets
ComponentVersion: 1.0.0
ComponentDescription: Uses the token exchange service to lists your S3 buckets.
ComponentPublisher: Amazon
ComponentDependencies:
  aws.greengrass.TokenExchangeService:
    VersionRequirement: ^2.0.0
    DependencyType: HARD
Manifests:
  - Platform:
      os: linux
    Lifecycle:
      install: 'docker load -i {artifacts:path}/list-s3-buckets.tar'
      Run: |
        docker run \
          --network=host \
          -e AWS_CONTAINER_AUTHORIZATION_TOKEN \
          -e AWS_CONTAINER_CREDENTIALS_FULL_URI \
          --rm list-s3-buckets
    Artifacts:
      - URI: s3://amzn-s3-demo-bucket/artifacts/com.example.python.docker.ListS3Buckets/1.0.0/list-s3-buckets.tar
```

## Use stream manager in Docker container components (Linux)


You can use the [stream manager component](stream-manager-component.md) to manage data streams in Greengrass components. This component enables you to process data streams and transfer high-volume IoT data to the AWS Cloud. AWS IoT Greengrass provides a stream manager SDK that you use to interact with the stream manager component. For more information, see [Manage data streams on Greengrass core devices](manage-data-streams.md).

**Note**  
The example in this section works only on Linux core devices.

To use the stream manager SDK in a Docker container component, you must run the Docker container with the following parameters:
+ Provide access to the host network using the `--network=host` argument. This option enables the Docker container to interact with the stream manager component over a local TLS connection. This argument works on only Docker for Linux
**Warning**  <a name="docker-network-host-security-warning"></a>
This option gives the container access to all local network interfaces on the host, so this option is less secure than if you run Docker containers without this access to the host network. Consider this when you develop and run Docker container components that use this option. For more information, see [Network: host](https://docs.docker.com/engine/reference/run/#network-host) in the *Docker Documentation*.
+ If you configure the stream manager component to require authentication, which is the default behavior, set the `AWS_CONTAINER_CREDENTIALS_FULL_URI` environment variable to the value that the Greengrass nucleus provides to components. For more information, see [stream manager configuration](stream-manager-component.md#stream-manager-component-configuration).
+ If you configure the stream manager component to use a non-default port, use [interprocess communication (IPC)](interprocess-communication.md) to get the port from the stream manager component configuration. You must run the Docker container with additional options to use IPC. For more information, see the following:
  + [Connect to stream manager in application code](use-stream-manager-in-custom-components.md#connect-to-stream-manager)
  + [Use interprocess communication in Docker container components](#docker-container-ipc)

**Example recipe: Stream a file to an S3 bucket in a Docker container component (Python)**  
The following recipe defines an example Docker container component that creates a file and streams it to an S3 bucket. This recipe has the following properties:  
+ The stream manager component as a dependency. This dependency enables the component to use the stream manager SDK to interact with the stream manager component.
+ A component artifact that specifies a Docker image as a TAR archive in Amazon S3.
+ A lifecycle install script that loads the Docker image from the TAR archive.
+ A lifecycle run script that runs a Docker container from the image. The [Docker run](https://docs.docker.com/engine/reference/run/) command has the following arguments:
  + The `--network=host` argument provides the container access to the host network, so the container can connect to the stream manager component.
  + The first `-e` argument sets the required `AWS_CONTAINER_AUTHORIZATION_TOKEN` environment variable in the Docker container.
  + The additional `-e` arguments set environment variables used by this example.
  + The `-v` argument mounts the component's [work folder](component-recipe-reference.md#component-recipe-work-path) in the container. This example creates a file in the work folder to upload that file to Amazon S3 using stream manager.
  + The `--rm` argument cleans up the container when it exits.

```
{
  "RecipeFormatVersion": "2020-01-25",
  "ComponentName": "com.example.python.docker.StreamFileToS3",
  "ComponentVersion": "1.0.0",
  "ComponentDescription": "Creates a text file and uses stream manager to stream the file to S3.",
  "ComponentPublisher": "Amazon",
  "ComponentDependencies": {
    "aws.greengrass.StreamManager": {
      "VersionRequirement": "^2.0.0",
      "DependencyType": "HARD"
    }
  },
  "ComponentConfiguration": {
    "DefaultConfiguration": {
      "bucketName": ""
    }
  },
  "Manifests": [
    {
      "Platform": {
        "os": "linux"
      },
      "Lifecycle": {
        "install": "docker load -i {artifacts:path}/stream-file-to-s3.tar",
        "Run": "docker run --network=host -e AWS_CONTAINER_AUTHORIZATION_TOKEN -e BUCKET_NAME=\"{configuration:/bucketName}\" -e WORK_PATH=\"{work:path}\" -v {work:path}:{work:path} --rm stream-file-to-s3"
      },
      "Artifacts": [
        {
          "URI": "s3://amzn-s3-demo-bucket/artifacts/com.example.python.docker.StreamFileToS3/1.0.0/stream-file-to-s3.tar"
        }
      ]
    }
  ]
}
```

```
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.python.docker.StreamFileToS3
ComponentVersion: 1.0.0
ComponentDescription: Creates a text file and uses stream manager to stream the file to S3.
ComponentPublisher: Amazon
ComponentDependencies:
  aws.greengrass.StreamManager:
    VersionRequirement: ^2.0.0
    DependencyType: HARD
ComponentConfiguration:
  DefaultConfiguration:
    bucketName: ''
Manifests:
  - Platform:
      os: linux
    Lifecycle:
      install: 'docker load -i {artifacts:path}/stream-file-to-s3.tar'
      Run: |
        docker run \
          --network=host \
          -e AWS_CONTAINER_AUTHORIZATION_TOKEN \
          -e BUCKET_NAME="{configuration:/bucketName}" \
          -e WORK_PATH="{work:path}" \
          -v {work:path}:{work:path} \
          --rm stream-file-to-s3
    Artifacts:
      - URI: s3://amzn-s3-demo-bucket/artifacts/com.example.python.docker.StreamFileToS3/1.0.0/stream-file-to-s3.tar
```

# AWS IoT Greengrass component recipe reference
Recipe reference

The component recipe is a file that defines a component's details, dependencies, artifacts, and lifecycles. The component *lifecycle* specifies the commands to run to install, run, and shut down the component, for example. The AWS IoT Greengrass core uses the lifecycles that you define in the recipe to install and run components. The AWS IoT Greengrass service uses the recipe to identify the dependencies and artifacts to deploy to your core devices when you deploy the component.

In the recipe, you can define unique dependencies and lifecycles for each platform that a component supports. You can use this capability to deploy a component to devices with multiple platforms that have different requirements. You can also use this to prevent AWS IoT Greengrass from installing a component on devices that don't support it.

Each recipe contains a list of *manifests*. Each manifest specifies a set of platform requirements and the lifecycle and artifacts to use for core devices whose platform meets those requirements. The core device uses the first manifest with platform requirements that the device meets. Specify a manifest without any platform requirements to match any core device.

You can also specify a global lifecycle that isn't in a manifest. In the global lifecycle, you can use *selection keys* that identify sub-sections of the lifecycle. Then, you can specify these selection keys within a manifest to use those sections of the global lifecycle in addition to the manifest's lifecycle. The core device uses the manifest's selection keys only if the manifest doesn't define a lifecycle. You can use the `all` selection in a manifest to match sections of the global lifecycle without selection keys.

After the AWS IoT Greengrass Core software selects a manifest that matches the core device, it does the following to identify the lifecycle steps to use:
+ If the selected manifest defines a lifecycle, the core device uses that lifecycle.
+ If the selected manifest doesn't define a lifecycle, the core device uses the global lifecycle. The core device does the following to identify which sections of the global lifecycle to use:
  + If the manifest defines selection keys, the core device uses the sections of the global lifecycle that contain the manifest's selection keys.
  + If the manifest doesn't define selection keys, the core device uses the sections of the global lifecycle that don't have selection keys. This behavior is equivalent to a manifest that defines the `all` selection.

**Important**  <a name="recipe-core-device-manifest-requirement"></a>
A core device must match least one manifest's platform requirements to install the component. If no manifest matches the core device, then the AWS IoT Greengrass Core software doesn't install the component and the deployment fails.

You can define recipes in [JSON](https://en.wikipedia.org/wiki/JSON) or [YAML](https://en.wikipedia.org/wiki/YAML) format. The recipe examples section includes recipes in each format.

**Topics**
+ [

## Recipe validation
](#recipe-validation)
+ [

## Recipe format
](#recipe-format)
+ [

## Recipe variables
](#recipe-variables)
+ [

## Recipe examples
](#recipe-examples)

## Recipe validation


Greengrass validates a JSON or YAML component recipe when creating a component version. This recipe validation checks your JSON or YAML component recipe for common errors in order to prevent potential deployment issues. The validation checks the recipe for common errors (e.g., missing commas, braces, and fields) and to make sure the recipe is well-formed.

If you receive a recipe validation error message, check your recipe for any missing commas, braces, or fields. Verify that you are not missing any fields by looking at the [recipe format](#recipe-format).

## Recipe format


When you define a recipe for a component, you specify the following information in the recipe document. The same structure applies to recipes in YAML and JSON formats.

`RecipeFormatVersion`  
The template version for the recipe. Choose the following option:  
+ `2020-01-25`

`ComponentName`  
The name of the component that this recipe defines. The component name must be unique in your AWS account in each Region.  
**Tips**  
+ Use inverse domain name format to avoid name collision within your company. For example, if your company owns `example.com` and you work on a solar energy project, you can name your Hello World component `com.example.solar.HelloWorld`. This helps avoid component name collisions within your company.
+ Avoid the `aws.greengrass` prefix in your component names. AWS IoT Greengrass uses this prefix for the [public components](public-components.md) that it provides. If you choose the same name as a public component, your component replaces that component. Then, AWS IoT Greengrass provides your component instead of the public component when it deploys components with a dependency on that public component. This feature enables you to override the behavior of public components, but it can also break other components if you don't intend to override a public component.

`ComponentVersion`  
The version of the component. The maximum value for the major, minor, and patch values is 999999.  
<a name="semver-para"></a>AWS IoT Greengrass uses semantic versions for components. Semantic versions follow a *major*.*minor*.*patch* number system. For example, version `1.0.0` represents the first major release for a component. For more information, see the [semantic version specification](https://semver.org/).

`ComponentDescription`  
(Optional) The description of the component.

`ComponentPublisher`  
The publisher or author of the component.

`ComponentConfiguration`  
(Optional) An object that defines the configuration or parameters for the component. You define the default configuration, and then when you deploy the component, you can specify the configuration object to provide to the component. Component configuration supports nested parameters and structures. This object contains the following information:    
`DefaultConfiguration`  
An object that defines the default configuration for the component. You define the structure of this object.  
<a name="configuration-value-type-note"></a>AWS IoT Greengrass uses JSON for configuration values. JSON specifies a number type but doesn't differentiate between integers and floats. As a result, configuration values might convert to floats in AWS IoT Greengrass. To ensure that your component uses the correct data type, we recommend that you define numeric configuration values as strings. Then, have your component parse them as integers or floats. This ensures that your configuration values have the same type in the configuration and on your core device.

`ComponentDependencies`  <a name="recipe-reference-component-dependencies"></a>
(Optional) A dictionary of objects that each define a component dependency for the component. The key for each object identifies the name of the component dependency. AWS IoT Greengrass installs component dependencies when the component installs. AWS IoT Greengrass waits for dependencies to start before it starts the component. Each object contains the following information:    
`VersionRequirement`  
The npm-style semantic version constraint that defines the compatible component versions for this dependency. You can specify a version or a range of versions. For more information, see the [npm semantic version calculator](https://semver.npmjs.com/).  
`DependencyType`  
(Optional) The type of this dependency. Choose from the following options.  
+ `SOFT` – The component doesn't restart if the dependency changes state.
+ `HARD` – The component restarts if the dependency changes state.
Defaults to `HARD`.

`ComponentType`  
(Optional) The type of component.  
We don't recommend that you specify the component type in a recipe. AWS IoT Greengrass sets the type for you when you create a component.
The type can be one the following types:  
+ `aws.greengrass.generic` – The component runs commands or provides artifacts.
+ `aws.greengrass.lambda` – The component runs a Lambda function using the [Lambda launcher component](lambda-launcher-component.md). The `ComponentSource` parameter specifies the ARN of the Lambda function that this component runs.

  We don't recommend that you use this option, because it's set by AWS IoT Greengrass when you create a component from a Lambda function. For more information, see [Run AWS Lambda functions](run-lambda-functions.md).
+ `aws.greengrass.plugin` – The component runs in the same Java Virtual Machine (JVM) as the Greengrass nucleus. If you deploy or restart a plugin component, the Greengrass nucleus restarts.

  Plugin components use the same log file as the Greengrass nucleus. For more information, see [Monitor AWS IoT Greengrass logs](monitor-logs.md).

  We don't recommend that you use this option in component recipes, because it's intended for AWS-provided components written in Java that directly interface with the Greengrass nucleus. For more information about which public components are plugins, see [AWS-provided components](public-components.md).
+ `aws.greengrass.nucleus` – The nucleus component. For more information, see [Greengrass nucleus](greengrass-nucleus-component.md).

  We don't recommend that you use this option in component recipes. It is intended for the Greengrass nucleus component, which provides the minimum functionality of the AWS IoT Greengrass Core software.
Defaults to `aws.greengrass.generic` when you create a component from a recipe, or `aws.greengrass.lambda` when you create a component from a Lambda function.  
For more information, see [Component types](develop-greengrass-components.md#component-types).

`ComponentSource`  
(Optional) The ARN of the Lambda function that a component runs.  
We don't recommend that you specify the component source in a recipe. AWS IoT Greengrass sets this parameter for you when you create a component from a Lambda function. For more information, see [Run AWS Lambda functions](run-lambda-functions.md).

  `Manifests`   
A list of objects that each define the component's lifecycle, parameters, and requirements for a platform. If a core device matches multiple manifests' platform requirements, AWS IoT Greengrass uses the first manifest that the core device matches. To ensure that core devices use the correct manifest, define the manifests with stricter platform requirements first. A manifest that applies to all platforms must be the last manifest in the list.  
A core device must match least one manifest's platform requirements to install the component. If no manifest matches the core device, then the AWS IoT Greengrass Core software doesn't install the component and the deployment fails.
Each object contains the following information:    
`Name`  
(Optional) A friendly name for the platform that this manifest defines.  
If you omit this parameter, AWS IoT Greengrass creates a name from the platform `os` and `architecture`.  
  `Platform`   
(Optional) An object that defines the platform to which this manifest applies. Omit this parameter to define a manifest that applies to all platforms.  
This object specifies key-value pairs about the platform on which a core device runs. When you deploy this component, the AWS IoT Greengrass Core software compares these key-value pairs with the platform attributes on the core device. The AWS IoT Greengrass Core software always defines `os` and `architecture`, and it might define additional attributes. You can specify custom platform attributes for a core device when you deploy the Greengrass nucleus component. For more information, see the [platform overrides parameter](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-platform-overrides) of the [Greengrass nucleus component](greengrass-nucleus-component.md).  
For each key-value pair, you can specify one of the following values:  
+ An exact value, such as `linux` or `windows`. Exact values must start with a letter or a number.
+ `*`, which matches any value. This also matches when a value isn't present.
+ A Java-style regular expression, such as `/windows|linux/`. The regular expression must start and end with a slash character (`/`). For example, the regular expression `/.+/` matches any non-blank value.
This object contains the following information:    
`runtime`  
The [Greengrass nucleus runtime](https://docs.aws.amazon.com/greengrass/v2/developerguide/how-it-works.html#concept-overview) for the platform that this manifest supports. When defining multiple manifests with platform `runtime`, The supported runtime values in a recipe are `aws_nucleus_lite` and `*` only. To target a classic device, runtime field MUST NOT be specified in the the recipe. Supported Greengrass Nucleus runtimes include the following values:  
+ `*`
+ `aws_nucleus_lite`  
`os`  
(Optional) The name of the operating system for the platform that this manifest supports. Common platforms include the following values:  
+ `linux`
+ `windows`
+ `darwin` (macOS)  
`architecture`  
(Optional) The processor architecture for the platform that this manifest supports. Common architectures include the following values:  
+ `amd64`
+ `arm`
+ `aarch64`
+ `x86`  
`architecture.detail`  
(Optional) The processor architecture detail for the platform that this manifest supports. Common architecture details include the following values:  
+ `arm61`
+ `arm71`
+ `arm81`  
`key`  
(Optional) A platform attribute that you define for this manifest. Replace *Key* with the name of the platform attribute. The AWS IoT Greengrass Core software matches this platform attribute with the key-value pairs that you specify in the Greengrass nucleus component configuration. For more information, see the [platform overrides parameter](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-platform-overrides) of the [Greengrass nucleus component](greengrass-nucleus-component.md).  
Use inverse domain name format to avoid name collision within your company. For example, if your company owns `example.com` and you work on a radio project, you can name a custom platform attribute `com.example.radio.RadioModule`. This helps avoid platform attribute name collisions within your company.
For example, you might define a platform attribute, `com.example.radio.RadioModule`, to specify a different manifest based on which radio module is available on a core device. Each manifest can include different artifacts that apply to different hardware configurations, so that you deploy the minimal set of software to the core device.  
  `Lifecycle`   
An object or string that defines how to install and run the component on the platform that this manifest defines. You can also define a [global lifecycle](#global-lifecycle-definition) that applies to all platforms. The core device uses the global lifecycle only if the manifest to use doesn't specify a lifecycle.  
You define this lifecycle within a manifest. The lifecycle steps that you specify here apply to only the platform that this manifest defines. You can also define a [global lifecycle](#global-lifecycle-definition) that applies to all platforms.
This object or string contains the following information:    
  `Setenv`   
(Optional) A dictionary of environment variables to provide to all lifecycle scripts. You can override these environment variables with `Setenv` in each lifecycle script.  
  `install`   
(Optional) An object or string that defines the script to run when the component installs. The AWS IoT Greengrass Core software also runs this lifecycle step each time the software launches.  
If the `install` script exits with a success code, the component enters the `INSTALLED` state.  
This object or string contains the following information:    
`Script`  <a name="recipe-lifecycle-script"></a>
The script to run.  
`RequiresPrivilege`  <a name="recipe-lifecycle-requiresprivilege"></a>
(Optional) You can run the script with root privileges. If you set this option to `true`, then the AWS IoT Greengrass Core software runs this lifecycle script as root instead of as the system user that you configure to run this component. Defaults to `false`.  
`Skipif`  <a name="recipe-lifecycle-skipif"></a>
(Optional) The check to determine whether or not to run the script. You can define to check if an executable is on the path or if a file exists. If the output is true, then the AWS IoT Greengrass Core software skips the step. Choose one of the following checks:  
+ `onpath runnable` – Check if a runnable is on the system path. For example, use **onpath python3** to skip this lifecycle step if Python 3 is available.
+ `exists file` – Check if a file exists. For example, use **exists /tmp/my-configuration.db** to skip this lifecycle step if `/tmp/my-configuration.db` is present.  
`Timeout`  <a name="recipe-lifecycle-timeout"></a>
(Optional) The maximum amount of time in seconds that the script can run before the AWS IoT Greengrass Core software terminates the process.  
Default: 120 seconds  
`Setenv`  <a name="recipe-lifecycle-environment"></a>
(Optional) The dictionary of environment variables to provide to the script. These environment variables override the variables that you provide in `Lifecycle.Setenv`.  
  `run`   
(Optional) An object or string that defines the script to run when the component starts.  
The component enters the `RUNNING` state when this lifecycle step runs. If the `run` script exits with a success code, the component enters the `STOPPING` state. If a `shutdown` script is specified, it runs; otherwise the component enters the `FINISHED` state.  
Components that depend on this component start when this lifecycle step runs. To run a background process, such as a service that dependent components use, use the `startup` lifecycle step instead.  
When you deploy components with a `run` lifecycle, the core device can report the deployment as complete as soon as this lifecycle script runs. As a result, the deployment can be complete and successful even if the `run` lifecycle script fails soon after running. If you want the deployment status to depend on the result of the component's start script, use the `startup` lifecycle step instead.  
You can define only one `startup` or `run` lifecycle.
This object or string contains the following information:    
`Script`  <a name="recipe-lifecycle-script"></a>
The script to run.  
`RequiresPrivilege`  <a name="recipe-lifecycle-requiresprivilege"></a>
(Optional) You can run the script with root privileges. If you set this option to `true`, then the AWS IoT Greengrass Core software runs this lifecycle script as root instead of as the system user that you configure to run this component. Defaults to `false`.  
`Skipif`  <a name="recipe-lifecycle-skipif"></a>
(Optional) The check to determine whether or not to run the script. You can define to check if an executable is on the path or if a file exists. If the output is true, then the AWS IoT Greengrass Core software skips the step. Choose one of the following checks:  
+ `onpath runnable` – Check if a runnable is on the system path. For example, use **onpath python3** to skip this lifecycle step if Python 3 is available.
+ `exists file` – Check if a file exists. For example, use **exists /tmp/my-configuration.db** to skip this lifecycle step if `/tmp/my-configuration.db` is present.  
`Timeout`  <a name="recipe-lifecycle-timeout"></a>
(Optional) The maximum amount of time in seconds that the script can run before the AWS IoT Greengrass Core software terminates the process.  
This lifecycle step doesn't timeout by default. If you omit this timeout, the `run` script runs until it exits.  
`Setenv`  <a name="recipe-lifecycle-environment"></a>
(Optional) The dictionary of environment variables to provide to the script. These environment variables override the variables that you provide in `Lifecycle.Setenv`.  
  `startup`   
(Optional) An object or string that defines the background process to run when the component starts.  
Use `startup` to run a command that must exit successfully or update the component's status to `RUNNING` before dependent components can start. Use the [UpdateState](ipc-component-lifecycle.md#ipc-operation-updatestate) IPC operation to set the component's status to `RUNNING` or `ERRORED` when the component starts a script that doesn't exit. For example, you might define a `startup` step that starts the MySQL process with `/etc/init.d/mysqld start`.  
The component enters the `STARTING` state when this lifecycle step runs. If the `startup` script exits with a success code, the component enters the `RUNNING` state. Then, dependent components can start.  
When you deploy components with a `startup` lifecycle, the core device can report the deployment as complete after this lifecycle script exits or reports its state. In other words, the deployment's status is `IN_PROGRESS` until all components' startup scripts exit or report a state.  
You can define only one `startup` or `run` lifecycle.
This object or string contains the following information:    
`Script`  <a name="recipe-lifecycle-script"></a>
The script to run.  
`RequiresPrivilege`  <a name="recipe-lifecycle-requiresprivilege"></a>
(Optional) You can run the script with root privileges. If you set this option to `true`, then the AWS IoT Greengrass Core software runs this lifecycle script as root instead of as the system user that you configure to run this component. Defaults to `false`.  
`Skipif`  <a name="recipe-lifecycle-skipif"></a>
(Optional) The check to determine whether or not to run the script. You can define to check if an executable is on the path or if a file exists. If the output is true, then the AWS IoT Greengrass Core software skips the step. Choose one of the following checks:  
+ `onpath runnable` – Check if a runnable is on the system path. For example, use **onpath python3** to skip this lifecycle step if Python 3 is available.
+ `exists file` – Check if a file exists. For example, use **exists /tmp/my-configuration.db** to skip this lifecycle step if `/tmp/my-configuration.db` is present.  
`Timeout`  <a name="recipe-lifecycle-timeout"></a>
(Optional) The maximum amount of time in seconds that the script can run before the AWS IoT Greengrass Core software terminates the process.  
Default: 120 seconds  
`Setenv`  <a name="recipe-lifecycle-environment"></a>
(Optional) The dictionary of environment variables to provide to the script. These environment variables override the variables that you provide in `Lifecycle.Setenv`.  
  `shutdown`   
(Optional) An object or string that defines the script to run when the component shuts down. Use the shutdown lifecycle to execute code that you want to run when the component is in the `STOPPING` state. The shutdown lifecycle can be used to stop a process started by the `startup` or `run` scripts.  
If you start a background process in `startup`, use the `shutdown` step to stop that process when the component shuts down. For example, you might define a `shutdown` step that stops the MySQL process with `/etc/init.d/mysqld stop`.  
The `shutdown` script runs after the component enters the `STOPPING` state. If the script completes successfully, the component enters the `FINISHED` state.  
This object or string contains the following information:    
`Script`  <a name="recipe-lifecycle-script"></a>
The script to run.  
`RequiresPrivilege`  <a name="recipe-lifecycle-requiresprivilege"></a>
(Optional) You can run the script with root privileges. If you set this option to `true`, then the AWS IoT Greengrass Core software runs this lifecycle script as root instead of as the system user that you configure to run this component. Defaults to `false`.  
`Skipif`  <a name="recipe-lifecycle-skipif"></a>
(Optional) The check to determine whether or not to run the script. You can define to check if an executable is on the path or if a file exists. If the output is true, then the AWS IoT Greengrass Core software skips the step. Choose one of the following checks:  
+ `onpath runnable` – Check if a runnable is on the system path. For example, use **onpath python3** to skip this lifecycle step if Python 3 is available.
+ `exists file` – Check if a file exists. For example, use **exists /tmp/my-configuration.db** to skip this lifecycle step if `/tmp/my-configuration.db` is present.  
`Timeout`  
(Optional) The maximum amount of time in seconds that the script can run before the AWS IoT Greengrass Core software terminates the process.  
Default: 15 seconds.  
`Setenv`  <a name="recipe-lifecycle-environment"></a>
(Optional) The dictionary of environment variables to provide to the script. These environment variables override the variables that you provide in `Lifecycle.Setenv`.  
  `recover`   
(Optional) An object or string that defines the script to run when the component encounters an error.  
This step runs when a component enters the `ERRORED` state. If the component becomes `ERRORED` three times without successfully recovering, the component changes to the `BROKEN` state. To fix a `BROKEN` component, you must deploy it again.  
This object or string contains the following information:    
`Script`  <a name="recipe-lifecycle-script"></a>
The script to run.  
`RequiresPrivilege`  <a name="recipe-lifecycle-requiresprivilege"></a>
(Optional) You can run the script with root privileges. If you set this option to `true`, then the AWS IoT Greengrass Core software runs this lifecycle script as root instead of as the system user that you configure to run this component. Defaults to `false`.  
`Skipif`  <a name="recipe-lifecycle-skipif"></a>
(Optional) The check to determine whether or not to run the script. You can define to check if an executable is on the path or if a file exists. If the output is true, then the AWS IoT Greengrass Core software skips the step. Choose one of the following checks:  
+ `onpath runnable` – Check if a runnable is on the system path. For example, use **onpath python3** to skip this lifecycle step if Python 3 is available.
+ `exists file` – Check if a file exists. For example, use **exists /tmp/my-configuration.db** to skip this lifecycle step if `/tmp/my-configuration.db` is present.  
`Timeout`  
(Optional) The maximum amount of time in seconds that the script can run before the AWS IoT Greengrass Core software terminates the process.  
Default: 60 seconds.  
`Setenv`  <a name="recipe-lifecycle-environment"></a>
(Optional) The dictionary of environment variables to provide to the script. These environment variables override the variables that you provide in `Lifecycle.Setenv`.  
  `bootstrap`   
(Optional) An object or string that defines a script that requires the AWS IoT Greengrass Core software or core device to restart. This lets you develop a component that performs a restart after it installs operating system updates or runtime updates, for example.  
To install updates or dependencies that don't require the AWS IoT Greengrass Core software or device to restart, use the [install lifecycle](#install-lifecycle-definition).
This lifecycle step runs before the install lifecycle step in the following cases when the AWS IoT Greengrass Core software deploys the component:  
+ The component deploys to the core device for the first time.
+ The component version changes.
+ The bootstrap script changes as the result of a component configuration update.
After the AWS IoT Greengrass Core software completes the bootstrap step for all components that have a bootstrap step in a deployment, the software restarts.  
You must configure the AWS IoT Greengrass Core software as a system service to restart the AWS IoT Greengrass Core software or the core device. If you don't configure the AWS IoT Greengrass Core software as a system service, the software won't restart. For more information, see [Configure the Greengrass nucleus as a system service](configure-greengrass-core-v2.md#configure-system-service).
This object or string contains the following information:    
`BootstrapOnRollback`  
When this feature is enabled, `BootstrapOnRollback` will only run for components that have either completed or attempted to run the bootstrap lifecycle steps as part of a failed target deployment. This feature is available for Greengrass nucleus versions 2.12.0 and later.
(Optional) You can run the bootstrap lifecycle steps as part of a rollback deployment. If you set this option to `true`, the bootstrap lifecycle steps defined within a rollback deployment will run. When a deployment fails, the previous version of the component bootstrap lifecycle will run again during a rollback deployment.  
Defaults to `false`.  
`Script`  
The script to run. The exit code of this script defines the restart instruction. Use the following exit codes:  
+ `0` – Don't restart the AWS IoT Greengrass Core software or the core device. The AWS IoT Greengrass Core software still restarts after all components bootstrap.
+ `100` – Request to restart the AWS IoT Greengrass Core software.
+ `101` – Request to restart the core device.
Exit codes 100 to 199 are reserved for special behavior. Other exit codes represent script errors.  
`RequiresPrivilege`  <a name="recipe-lifecycle-requiresprivilege"></a>
(Optional) You can run the script with root privileges. If you set this option to `true`, then the AWS IoT Greengrass Core software runs this lifecycle script as root instead of as the system user that you configure to run this component. Defaults to `false`.  
`Timeout`  <a name="recipe-lifecycle-timeout"></a>
(Optional) The maximum amount of time in seconds that the script can run before the AWS IoT Greengrass Core software terminates the process.  
Default: 120 seconds  
`Setenv`  <a name="recipe-lifecycle-environment"></a>
(Optional) The dictionary of environment variables to provide to the script. These environment variables override the variables that you provide in `Lifecycle.Setenv`.  
  `Selections`   
(Optional) A list of selection keys that specify sections of the [global lifecycle](#global-lifecycle-definition) to run for this manifest. In the global lifecycle, you can define lifecycle steps with selection keys at any level to select sub-sections of the lifecycle. Then, the core device uses those sections that match the selection keys in this manifest. For more information, see the [global lifecycle examples](#global-lifecycle-definition).  
The core device uses the selections from the global lifecycle only if this manifest doesn't define a lifecycle.
You can specify the `all` selection key to run sections of the global lifecycle that don't have selection keys.  
  `Artifacts`   
(Optional) A list of objects that each define a binary artifact for the component on the platform that this manifest defines. For example, you can define code or images as artifacts.  
When the component deploys, the AWS IoT Greengrass Core software downloads the artifact to a folder on the core device. You can also define artifacts as archive files that the software extracts after it downloads them.  
You can use [recipe variables](#recipe-variables) to get the paths to the folders where the artifacts install on the core device.  
+ Normal files – Use the [artifacts:path recipe variable](#component-recipe-artifacts-path) to get the path to the folder that contains the artifacts. For example, specify `{artifacts:path}/my_script.py` in a recipe to get the path to an artifact that has the URI `s3://amzn-s3-demo-bucket/path/to/my_script.py`.
+ Extracted archives – Use the [artifacts:decompressedPath recipe variable](#component-recipe-artifacts-decompressed-path) to get the path to the folder that contains the extracted archive artifacts. The AWS IoT Greengrass Core software extracts each archive to a folder with the same name as the archive. For example, specify `{artifacts:decompressedPath}/my_archive/my_script.py` in a recipe to get the path to `my_script.py` in the archive artifact that has the URI `s3://amzn-s3-demo-bucket/path/to/my_archive.zip`.
When you develop a component with an archive artifact on a local core device, you might not have a URI for that artifact. To test your component with an `Unarchive` option that extracts the artifact, specify a URI where the file name matches the name of your archive artifact file. You can specify the URI where you expect to upload the archive artifact, or you can specify a new placeholder URI. For example, to extract the `my_archive.zip` artifact during a local deployment, you can specify `s3://amzn-s3-demo-bucket/my_archive.zip`.
Each object contains the following information:    
`Uri`  
The URI of an artifact in an S3 bucket. The AWS IoT Greengrass Core software fetches the artifact from this URI when the component installs, unless the artifact already exists on the device. Each artifact must have a unique file name within each manifest.  
`Unarchive`  
(Optional) The type of archive to unpack. Choose from the following options:  
+ `NONE` – The file isn't an archive to unpack. The AWS IoT Greengrass Core software installs the artifact to a folder on the core device. You can use the [artifacts:path recipe variable](#component-recipe-artifacts-path) to get the path to this folder.
+ `ZIP` – The file is a ZIP archive. The AWS IoT Greengrass Core software extracts the archive to a folder with the same name as the archive. You can use the [artifacts:decompressedPath recipe variable](#component-recipe-artifacts-decompressed-path) to get the path to the folder that contains this folder.
Defaults to `NONE`.  
  `Permission`   
(Optional) An object that defines the access permissions to set for this artifact file. You can set the read permission and the execute permission.  
You can't set the write permission, because the AWS IoT Greengrass Core software doesn't allow components to edit artifact files in the artifacts folder. To edit an artifact file in a component, copy it to another location or publish and deploy a new artifact file.
If you define an artifact as an archive to unpack, then the AWS IoT Greengrass Core software sets these access permissions on the files that it unpacks from the archive. The AWS IoT Greengrass Core software sets the folder's access permissions to `ALL` for `Read` and `Execute`. This allows components to view the unpacked files in the folder. To set permissions on individual files from the archive, you can set the permissions in the [install lifecycle script](#install-lifecycle-definition).  
This object contains the following information:    
`Read`  
(Optional) The read permission to set for this artifact file. To allow other components to access this artifact, such as components that depend on this component, specify `ALL`. Choose from the following options:  
+ `NONE` – The file isn't readable.
+ `OWNER` – The file is readable by the system user that you configure to run this component.
+ `ALL` – The file is readable by all users.
Defaults to `OWNER`.  
`Execute`  
(Optional) The run permission to set for this artifact file. The `Execute` permission implies the `Read` permission. For example, if you specify `ALL` for `Execute`, then all users can read and run this artifact file.  
Choose from the following options:  
+ `NONE` – The file isn't runnable.
+ `OWNER` – The file is runnable by the system user that you configure to run the component.
+ `ALL` – The file is runnable by all users.
Defaults to `NONE`.  
`Digest`  
(Read-only) The cryptographic digest hash of the artifact. When you create a component, AWS IoT Greengrass uses a hash algorithm to calculate a hash of the artifact file. Then, when you deploy the component, the Greengrass nucleus calculates the hash of the downloaded artifact and compares the hash with this digest to verify the artifact before installation. If the hash doesn't match the digest, the deployment fails.  
If you set this parameter, AWS IoT Greengrass replaces the value that you set when you create the component.  
`Algorithm`  
(Read-only) The hash algorithm that AWS IoT Greengrass uses to calculate the digest hash of the artifact.  
If you set this parameter, AWS IoT Greengrass replaces the value that you set when you create the component.

  `Lifecycle`   
An object that defines how to install and run the component. The core device uses the global lifecycle only if the [manifest](#manifest-definition) to use doesn't specify a lifecycle.  
You define this lifecycle outside a manifest. You can also define a [manifest lifecycle](#manifest-lifecycle-definition) that applies to the platforms that match that manifest.
In the global lifecycle, you can specify lifecycles that run for certain [selection keys](#manifest-selections-definition) that you specify in each manifest. Selection keys are strings that identify sections of the global lifecycle to run for each manifest.  
The `all` selection key is the default on any section without a selection key. This means that you can specify the `all` selection key in a manifest to run the sections of the global lifecycle without selection keys. You don't need to specify the `all` selection key in the global lifecycle.  
If a manifest doesn't define a lifecycle or selection keys, the core device defaults to use the `all` selection. This means that in this case, the core device uses the sections of the global lifecycle that don't use selection keys.  
This object contains the same information as the [manifest lifecycle](#manifest-lifecycle-definition), but you can specify selection keys at any level to select sub-sections of the lifecycle.  
We recommend that you use only lowercase letters for each selection key to avoid conflicts between selection keys and lifecycle keys. Lifecycle keys start with a capital letter.

**Example global lifecycle with top-level selection keys**  

```
Lifecycle:
  key1:
    install:
      SkipIf: either onpath executable or exists file
      Script: command1
  key2:
    install:
      Script: command2
  all:
    install:
      Script: command3
```

**Example global lifecycle with bottom-level selection keys**  

```
Lifecycle:
  install:
    Script:
      key1: command1
      key2: command2
      all: command3
```

**Example global lifecycle with multiple levels of selection keys**  

```
Lifecycle:
  key1:
    install:
      SkipIf: either onpath executable or exists file
      Script: command1
  key2:
    install:
      Script: command2
  all:
    install:
      Script:
        key3: command3
        key4: command4
        all: command5
```

## Recipe variables


Recipe variables expose information from the current component and nucleus for you to use in your recipes. For example, you can use a recipe variable to pass component configuration parameters to an application that you run in a lifecycle script.

You can use recipe variables in the following sections of component recipes:
+ Lifecycle definitions.
+ Component configuration definitions, if you use [Greengrass nucleus](greengrass-nucleus-component.md) v2.6.0 or later and set the [interpolateComponentConfiguration](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-interpolate-component-configuration) configuration option to `true`. You can also use recipes variables when you [deploy component configuration updates](update-component-configurations.md#merge-configuration-update-recipe-variables).

Recipe variables use `{recipe_variable}` syntax. The curly braces indicate a recipe variable.

AWS IoT Greengrass supports the following recipe variables:

`component_dependency_name:configuration:json_pointer`  
The value of a configuration parameter for the component that this recipe defines or for a component on which this component depends.  
You can use this variable to provide a parameter to a script that you run in the component lifecycle.  
AWS IoT Greengrass supports this recipe variable only in component lifecycle definitions.
This recipe variable has the following inputs:  
+ <a name="recipe-variable-component-dependency-name"></a>`component_dependency_name` – (Optional) The name of the component dependency to query. Omit this segment to query the component that this recipe defines. You can specify only direct dependencies.
+ `json_pointer` – The JSON pointer to the configuration value to evaluate. JSON pointers start with a forward slash `/`. To identify a value in a nested component configuration, use forward slashes (`/`) to separate the keys for each level in the configuration. You can use a number as a key to specify an index in a list. For more information, see the [JSON pointer specification](https://tools.ietf.org/html/rfc6901).

  AWS IoT Greengrass Core uses JSON pointers for recipes in YAML format.
The JSON pointer can reference the following node types:  
+ A value node. AWS IoT Greengrass Core replaces the recipe variable with the string representation of the value. Null values convert to `null` as a string.
+ An object node. AWS IoT Greengrass Core replaces the recipe variable with the serialized JSON string representation of that object.
+ No node. AWS IoT Greengrass Core doesn't replace the recipe variable.
For example, the `{configuration:/Message}` recipe variable retrieves the value of the `Message` key in the component configuration. The `{com.example.MyComponentDependency:configuration:/server/port}` recipe variable retrieves the value of `port` in the `server` configuration object of a component dependency.

  `component_dependency_name:artifacts:path`   
The root path of the artifacts for the component that this recipe defines or for a component on which this component depends.  
When a component installs, AWS IoT Greengrass copies the component's artifacts to the folder that this variable exposes. You can use this variable to identify the location of a script to run in the component lifecycle, for example.  
<a name="recipe-variable-artifact-folder-permissions"></a>The folder at this path is read-only. To modify artifact files, copy the files to another location, such as the current working directory (`$PWD` or `.`). Then, modify the files there.  
<a name="recipe-variable-component-dependency-artifact-file-permissions"></a>To read or run an artifact from a component dependency, that artifact's `Read` or `Execute` permission must be `ALL`. For more information, see the [artifact permissions](#component-artifact-permission) that you define in the component recipe.  
This recipe variable has the following inputs:  
+ <a name="recipe-variable-component-dependency-name"></a>`component_dependency_name` – (Optional) The name of the component dependency to query. Omit this segment to query the component that this recipe defines. You can specify only direct dependencies.

  `component_dependency_name:artifacts:decompressedPath`   
The root path of the decompressed archive artifacts for the component that this recipe defines or for a component on which this component depends.  
When a component installs, AWS IoT Greengrass unpacks the component's archive artifacts to the folder that this variable exposes. You can use this variable to identify the location of a script to run in the component lifecycle, for example.  
Each artifact unzips to a folder within the decompressed path, where the folder has the same name as the artifact minus its extension. For example, a ZIP artifact named `models.zip` unpacks to the `{artifacts:decompressedPath}/models` folder.  
<a name="recipe-variable-artifact-folder-permissions"></a>The folder at this path is read-only. To modify artifact files, copy the files to another location, such as the current working directory (`$PWD` or `.`). Then, modify the files there.  
<a name="recipe-variable-component-dependency-artifact-file-permissions"></a>To read or run an artifact from a component dependency, that artifact's `Read` or `Execute` permission must be `ALL`. For more information, see the [artifact permissions](#component-artifact-permission) that you define in the component recipe.  
This recipe variable has the following inputs:  
+ <a name="recipe-variable-component-dependency-name"></a>`component_dependency_name` – (Optional) The name of the component dependency to query. Omit this segment to query the component that this recipe defines. You can specify only direct dependencies.

  `component_dependency_name:work:path`   
This feature is available for v2.0.4 and later of the [Greengrass nucleus component](greengrass-nucleus-component.md).  
The work path for the component that this recipe defines or for a component on which this component depends. The value of this recipe variable is equivalent to the output of the `$PWD` environment variable and the [pwd](https://en.wikipedia.org/wiki/Pwd) command when run from the context of the component.  
You can use this recipe variable to share files between a component and a dependency.  
The folder at this path is readable and writable by the component that this recipe defines and by other components that run as the same user and group.  
This recipe variable has the following inputs:  
+ <a name="recipe-variable-component-dependency-name"></a>`component_dependency_name` – (Optional) The name of the component dependency to query. Omit this segment to query the component that this recipe defines. You can specify only direct dependencies.

`kernel:rootPath`  
The AWS IoT Greengrass Core root path.

`iot:thingName`  
This feature is available for v2.3.0 and later of the [Greengrass nucleus component](greengrass-nucleus-component.md).  
The name of the core device's AWS IoT thing.

## Recipe examples


You can reference the following recipe examples to help you create recipes for your components.

AWS IoT Greengrass curates an index of Greengrass components, called the Greengrass Software Catalog. This catalog tracks Greengrass components that are developed by the Greengrass community. From this catalog, you can download, modify, and deploy components to create your Greengrass applications. For more information, see [Community components](greengrass-software-catalog.md).

**Topics**
+ [

### Hello World component recipe
](#recipe-example-hello-world)
+ [

### Python runtime component example
](#recipe-example-python-runtime)
+ [

### Component recipe that specifies several fields
](#recipe-example-all-fields)

### Hello World component recipe


The following recipe describes a Hello World component that runs a Python script. This component supports all platforms and accepts a `Message` parameter that AWS IoT Greengrass passes as an argument to the Python script. This is the recipe for the Hello World component in the [Getting started tutorial](getting-started.md).

------
#### [ JSON ]

```
{
  "RecipeFormatVersion": "2020-01-25",
  "ComponentName": "com.example.HelloWorld",
  "ComponentVersion": "1.0.0",
  "ComponentDescription": "My first AWS IoT Greengrass component.",
  "ComponentPublisher": "Amazon",
  "ComponentConfiguration": {
    "DefaultConfiguration": {
      "Message": "world"
    }
  },
  "Manifests": [
    {
      "Platform": {
        "os": "linux"
      },
      "Lifecycle": {
        "run": "python3 -u {artifacts:path}/hello_world.py {configuration:/Message}"
      }
    },
    {
      "Platform": {
        "os": "windows"
      },
      "Lifecycle": {
        "run": "py -3 -u {artifacts:path}/hello_world.py {configuration:/Message}"
      }
    }
  ]
}
```

------
#### [ YAML ]

```
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.HelloWorld
ComponentVersion: '1.0.0'
ComponentDescription: My first AWS IoT Greengrass component.
ComponentPublisher: Amazon
ComponentConfiguration:
  DefaultConfiguration:
    Message: world
Manifests:
  - Platform:
      os: linux
    Lifecycle:
      run: |
        python3 -u {artifacts:path}/hello_world.py "{configuration:/Message}"
  - Platform:
      os: windows
    Lifecycle:
      run: |
        py -3 -u {artifacts:path}/hello_world.py "{configuration:/Message}"
```

------

### Python runtime component example


The following recipe describes a component that installs Python. This component supports 64-bit Linux devices.

------
#### [ JSON ]

```
{
  "RecipeFormatVersion": "2020-01-25",
  "ComponentName": "com.example.PythonRuntime",
  "ComponentDescription": "Installs Python 3.7",
  "ComponentPublisher": "Amazon",
  "ComponentVersion": "3.7.0",
  "Manifests": [
    {
      "Platform": {
        "os": "linux",
        "architecture": "amd64"
      },
      "Lifecycle": {
        "install": "apt-get update\napt-get install python3.7"
      }
    }
  ]
}
```

------
#### [ YAML ]

```
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.PythonRuntime
ComponentDescription: Installs Python 3.7
ComponentPublisher: Amazon
ComponentVersion: '3.7.0'
Manifests:
  - Platform:
      os: linux
      architecture: amd64
    Lifecycle:
      install: |
        apt-get update
        apt-get install python3.7
```

------

### Component recipe that specifies several fields


The following component recipe uses several recipe fields.

------
#### [ JSON ]

```
{
  "RecipeFormatVersion": "2020-01-25",
  "ComponentName": "com.example.FooService",
  "ComponentDescription": "Complete recipe for AWS IoT Greengrass components",
  "ComponentPublisher": "Amazon",
  "ComponentVersion": "1.0.0",
  "ComponentConfiguration": {
    "DefaultConfiguration": {
      "TestParam": "TestValue"
    }
  },
  "ComponentDependencies": {
    "BarService": {
      "VersionRequirement": "^1.1.0",
      "DependencyType": "SOFT"
    },
    "BazService": {
      "VersionRequirement": "^2.0.0"
    }
  },
  "Manifests": [
    {
      "Platform": {
        "os": "linux",
        "architecture": "amd64"
      },
      "Lifecycle": {
        "install": {
          "Skipif": "onpath git",
          "Script": "sudo apt-get install git"
        },
        "Setenv": {
          "environment_variable1": "variable_value1",
          "environment_variable2": "variable_value2"
        }
      },
      "Artifacts": [
        {
          "Uri": "s3://amzn-s3-demo-bucket/hello_world.zip",
          "Unarchive": "ZIP"
        },
        {
          "Uri": "s3://amzn-s3-demo-bucket/hello_world_linux.py"
        }
      ]
    },
    {
      "Lifecycle": {
        "install": {
          "Skipif": "onpath git",
          "Script": "sudo apt-get install git",
          "RequiresPrivilege": "true"
        }
      },
      "Artifacts": [
        {
          "Uri": "s3://amzn-s3-demo-bucket/hello_world.py"
        }
      ]
    }
  ]
}
```

------
#### [ YAML ]

```
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.FooService
ComponentDescription: Complete recipe for AWS IoT Greengrass components
ComponentPublisher: Amazon
ComponentVersion: 1.0.0
ComponentConfiguration:
  DefaultConfiguration:
    TestParam: TestValue
ComponentDependencies:
  BarService:
    VersionRequirement: ^1.1.0
    DependencyType: SOFT
  BazService:
    VersionRequirement: ^2.0.0
Manifests:
  - Platform:
      os: linux
      architecture: amd64
    Lifecycle:
      install:
        SkipIf: onpath git
        Script: sudo apt-get install git
      SetEnv:
        environment_variable1: variable_value1
        environment_variable2: variable_value2
    Artifacts:
      - Uri: 's3://amzn-s3-demo-bucket/hello_world.zip'
        Unarchive: ZIP
      - Uri: 's3://amzn-s3-demo-bucket/hello_world_linux.py'
  - Lifecycle:
      install:
        SkipIf: onpath git
        Script: sudo apt-get install git
        RequiresPrivilege: 'true'
    Artifacts:
      - Uri: 's3://amzn-s3-demo-bucket/hello_world.py'
```

------

# Component environment variable reference
Environment variables

The AWS IoT Greengrass Core software sets environment variables when it runs lifecycle scripts for components. You can get these environment variables in your components to get the thing name, AWS Region, and Greengrass nucleus version. The software also sets environment variables that your component requires to use [the interprocess communication SDK](interprocess-communication.md) and to [interact with AWS services](interact-with-aws-services.md).

You can also set custom environment variables for your component's lifecycle scripts. For more information, see [Setenv](component-recipe-reference.md#lifecycle-setenv-definition).

The AWS IoT Greengrass Core software sets the following environment variables:

`AWS_IOT_THING_NAME`  
The name of the AWS IoT thing that represents this Greengrass core device.

`AWS_REGION`  
The AWS Region where this Greengrass core device operates.  
The AWS SDKs use this environment variable to identify the default Region to use. This variable is equivalent to `AWS_DEFAULT_REGION`.

`AWS_DEFAULT_REGION`  
The AWS Region where this Greengrass core device operates.  
The AWS CLI uses this environment variable to identify the default Region to use. This variable is equivalent to `AWS_REGION`.

`GGC_VERSION`  
The version of the [Greengrass nucleus component](greengrass-nucleus-component.md) that runs on this Greengrass core device.

`GG_ROOT_CA_PATH`  
This feature is available for v2.5.5 and later of the [Greengrass nucleus component](greengrass-nucleus-component.md).  
The path to the root certificate authority (CA) certificate that the Greengrass nucleus uses.

`AWS_GG_NUCLEUS_DOMAIN_SOCKET_FILEPATH_FOR_COMPONENT`  
The path to the IPC socket that components use to communicate with the AWS IoT Greengrass Core software. For more information, see [Use the AWS IoT Device SDK to communicate with the Greengrass nucleus, other components, and AWS IoT CoreCommunicate with the Greengrass nucleus, other components, and AWS IoT Core](interprocess-communication.md).

`SVCUID`  
The secret token that components use to connect to the IPC socket and communicate with the AWS IoT Greengrass Core software. For more information, see [Use the AWS IoT Device SDK to communicate with the Greengrass nucleus, other components, and AWS IoT CoreCommunicate with the Greengrass nucleus, other components, and AWS IoT Core](interprocess-communication.md).

`AWS_CONTAINER_AUTHORIZATION_TOKEN`  
The secret token that components use to retrieve credentials from the [token exchange service component](token-exchange-service-component.md).

`AWS_CONTAINER_CREDENTIALS_FULL_URI`  
The URI that components request to retrieve credentials from the [token exchange service component](token-exchange-service-component.md).

# Deploy AWS IoT Greengrass components to devices
Deploy components to devices

You can use AWS IoT Greengrass to deploy components to devices or groups of devices. You use *deployments* to define the components and configurations that are sent to the devices. AWS IoT Greengrass deploys to *targets*, AWS IoT things or thing groups that represent Greengrass core devices. AWS IoT Greengrass uses [AWS IoT Core jobs](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html) to deploy to your core devices. You can configure how the job rolls out to your devices.

## Core device deployments


Each core device runs the components of the deployments for that device. A new deployment to the same target overwrites the previous deployment to the target. When you create a deployment, you define the components and configurations to apply to the core device's existing software.

When you revise a deployment for a target, you replace the components from the previous revision with the components in the new revision. For example, you deploy the [Log manager](log-manager-component.md) and [Secret manager](secret-manager-component.md) components to the thing group `TestGroup`. Then you create another deployment for `TestGroup` that specifies only the secret manager component. As a result, the core devices in that group no longer run the log manager.

## Platform dependency resolution


When a core device receives a deployment, it checks to make sure that the components are compatible with the core device. For example, if you deploy the [Firehose](kinesis-firehose-component.md) to a Windows target, the deployment will fail.

## Component dependency resolution


During a component deployment, the core device verifies compatibility of all components' dependencies and version requirements across a thing group. This verification ensures that version contraints are satisfied for all components and their dependencies before proceeding with the deployment.

The dependency resolution process begins with identifying target components that have no dependencies in their recipes. Then, the system constructs a dependency tree using breadth-first search (BFS) which systematically explores each target node and finds their dependencies first before moving on to the next node. Each node includes the target component as the key and the version requirements as the value.

The version requirements combine three sets of constraints:
+ The version requirements that are already established in the existing thing group.
+ The component version required by the deployment. You must select a component version when you make or update a deployment.
+ Any component version constraints that are defined within the recipe's dependency section.

### Resolve component dependencies


During a deployment, the Greengrass nucleus first attempts to find the local candidate currently running on the device that satisfies the requirements. If the running component satisfies the requirements, the nucleus gets the stored recipe path from the recipe folder and finds the latest local version in the local store.

For AWS Cloud deployments, the nucleus will then call the [ResolveComponentCandidates API](https://docs.aws.amazon.com/greengrass/v2/APIReference/API_ResolveComponentCandidates.html). This API will start with the latest available version and check if it satisfies the dependencies and requirements. When the nucleus gets the response from the API, it selects that latest version. If there is no version found from the AWS Cloud that satisfies the requirements, the deployment fails. If the device is offline, it falls back to the original local candidate found. If there is no local candidate found that satisfies the requirements, the deployment fails.

For local deployments, the nucleus exclusively uses local candidates if they exist and if they satisfy the requirements without negotiating to AWS Cloud. If there is no such candidate, the deployment fails.

**Note**  
All resolved recipes are stored locally for future reference.

For more information, see the [dependency resolution](https://github.com/aws-greengrass/aws-greengrass-nucleus/wiki/Deployment#dependency-resolution) section in GitHub.

If the Greengrass nucleus is able to successfully resolve all components, the nucleus log will contain the following line.

```
resolve-all-group-dependencies-finish. Finish resolving all groups dependencies.
```

**Example**  
The following is an example of how the nucleus will resolve the component requirements.  
+ You deploy ComponentA which depends on ComponentC versions 1.0.0-1.9.0.
+ You also deploy ComponentB which depends on ComponentC versions 1.4.0-1.9.5.
With component dependency resolution, the nucleus will deploy the latest version of ComponentC version to satisfy the requirements of ComponentA and ComponentB. This latest version of ComponentC is version 1.9.0.

#### Common component dependency resolution failures


The component dependency resolution may fail for two main reasons: target version requirement conflict or component dependency requirement conflict.

##### Scenario 1: Target version requirement conflict

+ A thing exists in one thing group and you also want to add that thing to a new thing group. The deployment will fail if the new thing group requires a different thing version.
+ A deployment may also fail if a thing belongs to a thing group and wants to update the component version through a thing deployment.

![\[Component dependencies that result in a failed deployment.\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/images/dependency-4.png)


*Failure log sample:*

```
2025-04-11T06:16:03.315Z [ERROR] (pool-3-thread-27) com.aws.greengrass.componentmanager.ComponentManager: Failed to negotiate version with cloud and no local version to fall back to. {componentName=ComponentC, versionRequirement={thing/ABC==2.0.0, thinggroup/ThingGroupA==1.0.0}}
2025-04-11T06:16:03.316Z [ERROR] (pool-3-thread-26) com.aws.greengrass.deployment.DeploymentService: Error occurred while processing deployment. {deploymentId=fbac24de-4ef9-44b0-a685-fdc63b0f02b8, serviceName=DeploymentService, currentState=RUNNING}
java.util.concurrent.ExecutionException: com.aws.greengrass.componentmanager.exceptions.NoAvailableComponentVersionException: No local or cloud component version satisfies the requirements Check whether the version constraints conflict and that the component exists in your AWS account with a version that matches the version constraints. If the version constraints conflict, revise deployments to resolve the conflict. Component ComponentC version constraints: thing/ABC requires =2.0.0, thinggroup/ThingGroupA requires =1.0.0.
    at java.base/java.util.concurrent.FutureTask.report(FutureTask.java:122)
    at java.base/java.util.concurrent.FutureTask.get(FutureTask.java:191)
    at com.aws.greengrass.deployment.DefaultDeploymentTask.call(DefaultDeploymentTask.java:127)
    at com.aws.greengrass.deployment.DefaultDeploymentTask.call(DefaultDeploymentTask.java:50)
    at java.base/java.util.concurrent.FutureTask.run(FutureTask.java:264)
    at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1128)
    at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:628)
    at java.base/java.lang.Thread.run(Thread.java:829)
Caused by: com.aws.greengrass.componentmanager.exceptions.NoAvailableComponentVersionException: No local or cloud component version satisfies the requirements Check whether the version constraints conflict and that the component exists in your AWS account with a version that matches the version constraints. If the version constraints conflict, revise deployments to resolve the conflict. Component ComponentC version constraints: thing/ABC requires =2.0.0, thinggroup/ThingGroupA requires =1.0.0.
    at com.aws.greengrass.componentmanager.ComponentManager.negotiateVersionWithCloud(ComponentManager.java:232)
    at com.aws.greengrass.componentmanager.ComponentManager.resolveComponentVersion(ComponentManager.java:167)
    at com.aws.greengrass.componentmanager.DependencyResolver.lambda$resolveDependencies$0(DependencyResolver.java:134)
    at com.aws.greengrass.componentmanager.DependencyResolver.resolveComponentDependencies(DependencyResolver.java:231)
    at com.aws.greengrass.componentmanager.DependencyResolver.resolveDependencies(DependencyResolver.java:131)
    at com.aws.greengrass.deployment.DefaultDeploymentTask.lambda$call$2(DefaultDeploymentTask.java:125)
    ... 4 more
```

The logs indicate a version conflict error because the nucleus can't find a component version that simultaneously meetings two conflicting requirements.

##### How to resolve it

+ If you want to keep the component in each thing group, select the same version of that component in each thing group.
+ Select a component version that meets the deployment requirement.
+ If you want to use a component version that doesn't meet both thing group requirements, select the component version that meets the thing group version requirement and use that component only in that thing group.

##### Scenario 2: Component dependency version requirement conflict


If a component is a dependency of different components and the components require different versions or different version ranges of that component, there a possibility that there are no available versions to satisfy all version requirements. In this scenario, the deployment will fail.

**Example**  
Deployment of ComponentA (v2.5.0), ComponentB (v1.3.0), and ComponentC (v1.0.0)  
+ ComponentA requires ComponentB version >=1.0.0.

  ```
  ---
  ...
  ComponentName: ComponentA
  ComponentVersion: "2.5.0"
  ComponentDependencies:
      ComponentB:
          VersionRequirement: ">=1.0.0"
          DependencyType: "HARD"
  ...
  ```
+ ComponentC requires ComponentA version <2.0.0.

  ```
  ---
  ...
  ComponentName: ComponentC
  ComponentVersion: "1.0.0"
  ComponentDependencies:
      ComponentA:
          VersionRequirement: "<2.0.0"
          DependencyType: "HARD"
  ...
  ```
There's a version conflict between two requirements for ComponentA:  
+ ComponentA requires version 2.5.0 in this deployment
+ ComponentC requires ComponentA versions lower than 2.0.0
These two requirements contradict each other, making it impossible for the nucleus to find a ComponentA version that satisfies both requirements. Therefore, the dependency resolution fails.

![\[Component dependencies that result in a failed deployment.\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/images/dependency-3.png)


*Failure log sample:*

```
2025-04-11T06:07:18.291Z [ERROR] (pool-3-thread-25) com.aws.greengrass.componentmanager.ComponentManager: Failed to negotiate version with cloud and no local version to fall back to. {componentName=ComponentA, versionRequirement={ComponentC=<2.0.0, thinggroup/ThingGroupA==2.5.0}}
2025-04-11T06:07:18.292Z [ERROR] (pool-3-thread-24) com.aws.greengrass.deployment.DeploymentService: Error occurred while processing deployment. {deploymentId=2ffac4df-1ac9-405c-8c11-28494a1b4382, serviceName=DeploymentService, currentState=RUNNING}
java.util.concurrent.ExecutionException: com.aws.greengrass.componentmanager.exceptions.NoAvailableComponentVersionException: No local or cloud component version satisfies the requirements Check whether the version constraints conflict and that the component exists in your AWS account with a version that matches the version constraints. If the version constraints conflict, revise deployments to resolve the conflict. Component ComponentA version constraints: ComponentC requires <2.0.0, thinggroup/ThingGroupA requires =2.5.0.
    at java.base/java.util.concurrent.FutureTask.report(FutureTask.java:122)
    at java.base/java.util.concurrent.FutureTask.get(FutureTask.java:191)
    at com.aws.greengrass.deployment.DefaultDeploymentTask.call(DefaultDeploymentTask.java:127)
    at com.aws.greengrass.deployment.DefaultDeploymentTask.call(DefaultDeploymentTask.java:50)
    at java.base/java.util.concurrent.FutureTask.run(FutureTask.java:264)
    at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1128)
    at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:628)
    at java.base/java.lang.Thread.run(Thread.java:829)
Caused by: com.aws.greengrass.componentmanager.exceptions.NoAvailableComponentVersionException: No local or cloud component version satisfies the requirements Check whether the version constraints conflict and that the component exists in your AWS account with a version that matches the version constraints. If the version constraints conflict, revise deployments to resolve the conflict. Component ComponentA version constraints: ComponentC requires <2.0.0, thinggroup/ThingGroupA requires =2.5.0.
    at com.aws.greengrass.componentmanager.ComponentManager.negotiateVersionWithCloud(ComponentManager.java:232)
    at com.aws.greengrass.componentmanager.ComponentManager.resolveComponentVersion(ComponentManager.java:167)
    at com.aws.greengrass.componentmanager.DependencyResolver.lambda$resolveDependencies$0(DependencyResolver.java:134)
    at com.aws.greengrass.componentmanager.DependencyResolver.resolveComponentDependencies(DependencyResolver.java:231)
    at com.aws.greengrass.componentmanager.DependencyResolver.resolveDependencies(DependencyResolver.java:131)
    at com.aws.greengrass.deployment.DefaultDeploymentTask.lambda$call$2(DefaultDeploymentTask.java:125)
    ... 4 more
```

The logs indicate that the nucleus can't find a version of ComponentA that satisfies the following requirements.
+ The requirements for ComponentA to be exactly version 2.5.0 (from ThingGroupA).
+ The requirement to work with ComponentC versions below 2.0.0.

##### How to resolve it

+ If you want to keep the component in each thing group, select the same version of that component in each thing group.
+ Select a component version that meets the deployment requirement.
+ If you want to use a component version that doesn't meet both thing group requirements, select the component version that meets the thing group version requirement and use that component only in that thing group.

**Tip**  
If you see this error on any AWS provided component, you can resolve it by updating the conflicted components to the latest version.

## Removing a device from a thing group


When you remove a core device from a thing group, the component deployment behavior depends on the version of the [Greengrass nucleus](greengrass-nucleus-component.md) that the core device runs.

------
#### [ 2.5.1 and later ]

When you remove a core device from a thing group, the behavior depends on whether the AWS IoT policy grants the `greengrass:ListThingGroupsForCoreDevice` permission. For more information about this permission and AWS IoT policies for core devices, see [Device authentication and authorization for AWS IoT Greengrass](device-auth.md).
+ **If the AWS IoT policy grants this permission**

  <a name="thing-group-removal-behavior-remove-components"></a>When you remove a core device from a thing group, AWS IoT Greengrass removes the thing group's components the next time a deployment is made to the device. If a component on the device is included in the next deployment, that component is not removed from the device.
+ **If the AWS IoT policy doesn't grant this permission**

  <a name="thing-group-removal-behavior-no-remove-components"></a>When you remove a core device from a thing group, AWS IoT Greengrass doesn't delete that thing group's components from the device.

  <a name="thing-group-removal-behavior-no-remove-components-how-to-remove"></a>To remove a component from a device, use the [deployment create](gg-cli-deployment.md#deployment-create) command of the Greengrass CLI. Specify the component to remove with the `--remove` argument, and specify the thing group with the `--groupId` argument.

------
#### [ 2.5.0 ]

<a name="thing-group-removal-behavior-remove-components"></a>When you remove a core device from a thing group, AWS IoT Greengrass removes the thing group's components the next time a deployment is made to the device. If a component on the device is included in the next deployment, that component is not removed from the device.

This behavior requires that the core device's AWS IoT policy grants the `greengrass:ListThingGroupsForCoreDevice` permission. If a core device doesn't have this permission, the core device fails to apply deployments. For more information, see [Device authentication and authorization for AWS IoT Greengrass](device-auth.md).

------
#### [ 2.0.x - 2.4.x ]

<a name="thing-group-removal-behavior-no-remove-components"></a>When you remove a core device from a thing group, AWS IoT Greengrass doesn't delete that thing group's components from the device.

<a name="thing-group-removal-behavior-no-remove-components-how-to-remove"></a>To remove a component from a device, use the [deployment create](gg-cli-deployment.md#deployment-create) command of the Greengrass CLI. Specify the component to remove with the `--remove` argument, and specify the thing group with the `--groupId` argument.

------

## Deployments


Deployments are continuous. When you create a deployment, AWS IoT Greengrass rolls out the deployment to target devices that are online. If a target device isn't online, then it receives the deployment the next time it connects to AWS IoT Greengrass. When you add a core device to a target thing group, AWS IoT Greengrass sends the device the latest deployment for that thing group.

Before a core device deploys a component, by default it notifies each component on the device. Greengrass components can respond to the notification to defer deployment. You might want to defer deployment if the device has a low battery level or is running a process that can't be interrupted. For more information, see [Tutorial: Develop a Greengrass component that defers component updates](defer-component-updates-tutorial.md). When you create a deployment you can configure it to deploy without notifying components.

Each target thing or thing group can have one deployment at a time. This means that when you create a deployment for a target, AWS IoT Greengrass no longer deploys the previous revision of that target's deployment.

## Deployment options


Deployments provide several options that let you control which devices receive an update and how the update deploys. When you create a deployment, you can configure the following options:
+ **AWS IoT Greengrass components**

  Define the components to install and run on the target devices. AWS IoT Greengrass components are software modules that you deploy and run on Greengrass core devices. Devices receive components only if the component supports the device's platform. This lets you deploy to groups of devices even if the target devices run on multiple platforms. If a component doesn't support the device's platform, the component doesn't deploy to the device.

  You can deploy custom components and AWS-provided components to your devices. When you deploy a component, AWS IoT Greengrass identifies any component dependencies and deploys them too. For more information, see [Develop AWS IoT Greengrass components](develop-greengrass-components.md) and [AWS-provided components](public-components.md).

  You define the version and configuration update to deploy for each component. The *configuration update* specifies how to modify the component's existing configuration on the core device, or the component's default configuration if the component doesn't exist on the core device. You can specify which configuration values to reset to default values and the new configuration values to merge onto the core device. When a core device receives deployments for different targets, and each deployment specifies compatible component versions, the core device applies configuration updates in order based on the timestamp of when you create the deployment. For more information, see [Update component configurations](update-component-configurations.md).
**Important**  <a name="component-patch-update-note"></a>
<a name="component-patch-update"></a>When you deploy a component, AWS IoT Greengrass installs the latest supported versions of all of that component's dependencies. Because of this, new patch versions of AWS-provided public components might be automatically deployed to your core devices if you add new devices to a thing group, or you update the deployment that targets those devices. Some automatic updates, such as a nucleus update, can cause your devices to restart unexpectedly.   
<a name="component-version-pinning"></a>To prevent unintended updates for a component that is running on your device, we recommend that you directly include your preferred version of that component when you [create a deployment](create-deployments.md). For more information about update behavior for AWS IoT Greengrass Core software, see [Update the AWS IoT Greengrass Core software (OTA)](update-greengrass-core-v2.md).
+ **Deployment policies**

  Define when it's safe to deploy a configuration and what to do if the deployment fails. You can specify whether or not to wait for components to report that they can update. You can also specify whether or not to roll back devices to their previous configuration if they apply a deployment that fails.
+ **Stop configuration**

  Define when and how to stop a deployment. The deployment stops and fails if the criteria that you define are met. For example, you can configure a deployment to stop if a percentage of devices fail to apply that deployment after a minimum number of devices receive it.
+ **Rollout configuration**

  Define the rate at which a deployments rolls out to the target devices. You can configure an exponential rate increase with minimum and maximum rate bounds.
+ **Timeout configuration**

  Define the maximum amount of time each device has to apply a deployment. If a device exceeds the duration that you specify, then the device fails to apply the deployment.

**Important**  
Custom components can define artifacts in S3 buckets. When the AWS IoT Greengrass Core software deploys a component, it downloads the component's artifacts from the AWS Cloud. Core device roles don't allow access to S3 buckets by default. To deploy custom components that define artifacts in an S3 bucket, the core device role must grant permissions to download artifacts from that bucket. For more information, see [Allow access to S3 buckets for component artifacts](device-service-role.md#device-service-role-access-s3-bucket).

**Topics**
+ [

## Core device deployments
](#core-device-deployments)
+ [

## Platform dependency resolution
](#platform-dependency-resolution)
+ [

## Component dependency resolution
](#component-dependency-resolution)
+ [

## Removing a device from a thing group
](#thing-group-removal-behavior)
+ [

## Deployments
](#deployments)
+ [

## Deployment options
](#deployment-options)
+ [

# Create deployments
](create-deployments.md)
+ [

# Create subdeployments
](create-subdeployments.md)
+ [

# Revise deployments
](revise-deployments.md)
+ [

# Cancel deployments
](cancel-deployments.md)
+ [

# Check deployment status
](check-deployment-status.md)

# Create deployments


You can create a deployment that targets a thing or thing group.

When you create a deployment, you configure the software components to deploy and how the deployment job rolls out to target devices. You can define the deployment in the JSON file that you provide to the AWS CLI.

The deployment target determines the devices on which you want to run your components. To deploy to one core device, specify a thing. To deploy to multiple core devices, specify a thing group that includes those devices. For more information about how to configure thing groups, see [Static thing groups](https://docs.aws.amazon.com/iot/latest/developerguide/thing-groups.html) and [Dynamic thing groups](https://docs.aws.amazon.com/iot/latest/developerguide/dynamic-thing-groups.html) in the *AWS IoT Developer Guide*.

Follow the steps in this section to create a deployment to a target. For more information about how to update the software components on a target that has a deployment, see [Revise deployments](revise-deployments.md).

**Warning**  
The [CreateDeployment](https://docs.aws.amazon.com/greengrass/v2/APIReference/API_CreateDeployment.html) operation can uninstall components from core devices. If a component is present in the previous deployment and not the new deployment, the core device uninstalls that component. To avoid uninstalling components, first use the [ListDeployments](https://docs.aws.amazon.com/greengrass/v2/APIReference/API_ListDeployments.html) operation to check if the target for the deployment already has an existing deployment. Then, use the [GetDeployment](https://docs.aws.amazon.com/greengrass/v2/APIReference/API_GetDeployment.html) operation to start from that existing deployment when you create a new deployment.

**To create a deployment (AWS CLI)**

1. Create a file called `deployment.json`, and then copy the following JSON object into the file. Replace *targetArn* with the ARN of the AWS IoT thing or thing group to target for the deployment. Thing and thing group ARNs have the following format:
   + Thing: `arn:aws:iot:region:account-id:thing/thingName`
   + Thing group: `arn:aws:iot:region:account-id:thinggroup/thingGroupName`

   ```
   {
     "targetArn": "targetArn"
   }
   ```

1. Check if the deployment target has an existing deployment that you want to revise. Do the following:

   1. <a name="revise-deployment-list-deployments-intro"></a>Run the following command to list the deployments for the deployment target. Replace *targetArn* with the ARN of the target AWS IoT thing or thing group.

      ```
      aws greengrassv2 list-deployments --target-arn targetArn
      ```

      The response contains a list with the latest deployment for the target. If the response is empty, the target doesn't have an existing deployment, and you can skip to [Step 3](#create-deployment-define-name-step). Otherwise, copy the `deploymentId` from the response to use in the next step.
**Note**  <a name="revise-deployment-list-deployments-revision-note"></a>
You can also revise a deployment other than the latest revision for the target. Specify the `--history-filter ALL` argument to list all deployments for the target. Then, copy the ID of the deployment that you want to revise.

   1. <a name="revise-deployment-get-deployment"></a>Run the following command to get the deployment's details. These details include metadata, components, and job configuration. Replace *deploymentId* with the ID from the previous step.

      ```
      aws greengrassv2 get-deployment --deployment-id deploymentId
      ```

      The response contains the deployment's details.

   1. Copy any of the following key-value pairs from the previous command's response into `deployment.json`. You can change these values for the new deployment.
      + `deploymentName` – The deployment's name.
      + `components` – The deployment's components. To uninstall a component, remove it from this object.
      + `deploymentPolicies` – The deployment's policies.
      + `iotJobConfiguration` – The deployment's job configuration.
      + `tags` – The deployment's tags.

1. <a name="create-deployment-define-name-step"></a>(Optional) Define a name for the deployment. Replace *deploymentName* with the name of the deployment.

   ```
   {
     "targetArn": "targetArn",
     "deploymentName": "deploymentName"
   }
   ```

1. Add each component to deploy the target devices. To do so, add key-value pairs to the `components` object, where the key is the component name, and the value is an object that contains the details for that component. Specify the following details for each component that you add:
   + `version` – The component version to deploy.
   + `configurationUpdate` – The [configuration update](update-component-configurations.md) to deploy. The update is a patch operation that modifies the component's existing configuration on each target device, or the component's default configuration if it doesn't exist on the target device. You can specify the following configuration updates:
     + Reset updates (`reset`) – (Optional) A list of JSON pointers that define the configuration values to reset to their default values on the target device. The AWS IoT Greengrass Core software applies reset updates before it applies merge updates. For more information, see [Reset updates](update-component-configurations.md#reset-configuration-update).
     + Merge updates (`merge`) – (Optional) A JSON document that defines the configuration values to merge onto the target device. You must serialize the JSON document as a string. For more information, see [Merge updates](update-component-configurations.md#merge-configuration-update).
   + <a name="component-run-with-config"></a>`runWith` – (Optional) The system process options that the AWS IoT Greengrass Core software uses to run this component's processes on the core device. If you omit a parameter in the `runWith` object, the AWS IoT Greengrass Core software uses the default values that you configure on the [Greengrass nucleus component](greengrass-nucleus-component.md).

     You can specify any of the following options:
     + `posixUser` – The POSIX system user and, optionally, group to use to run this component on Linux core devices. The user, and group if specified, must exist on each Linux core device. Specify the user and group separated by a colon (`:`) in the following format: `user:group`. The group is optional. If you don't specify a group, the AWS IoT Greengrass Core software uses the primary group for the user. For more information, see [Configure the user that runs components](configure-greengrass-core-v2.md#configure-component-user).
     + `windowsUser` – The Windows user to use to run this component on Windows core devices. The user must exist on each Windows core device, and its name and password must be stored in the LocalSystem account's Credentials Manager instance. For more information, see [Configure the user that runs components](configure-greengrass-core-v2.md#configure-component-user).

       This feature is available for v2.5.0 and later of the [Greengrass nucleus component](greengrass-nucleus-component.md).
     + `systemResourceLimits` – The system resource limits to apply to this component's processes. You can apply system resource limits to generic and non-containerized Lambda components. For more information, see [Configure system resource limits for components](configure-greengrass-core-v2.md#configure-component-system-resource-limits).

       You can specify any of the following options:
       + `cpus` – <a name="system-resource-limits-cpu-definition-this"></a>The maximum amount of CPU time that this component's processes can use on the core device. A core device's total CPU time is equivalent to the device's number of CPU cores. For example, on a core device with 4 CPU cores, you can set this value to `2` to limit this component's processes to 50 percent usage of each CPU core. On a device with 1 CPU core, you can set this value to `0.25` to limit this component's processes to 25 percent usage of the CPU. If you set this value to a number greater than the number of CPU cores, the AWS IoT Greengrass Core software doesn't limit the component's CPU usage. 
       + `memory` – <a name="system-resource-limits-memory-definition-this"></a>The maximum amount of RAM (in kilobytes) that this component's processes can use on the core device. 

       This feature is available for v2.4.0 and later of the [Greengrass nucleus component](greengrass-nucleus-component.md). AWS IoT Greengrass doesn't currently support this feature on Windows core devices. 

      
**Example basic configuration update**  

   The following example `components` object specifies to deploy a component, `com.example.PythonRuntime`, that expects a configuration parameter named `pythonVersion`.

   ```
   {
     "targetArn": "targetArn",
     "deploymentName": "deploymentName",
     "components": {
       "com.example.PythonRuntime": {
         "componentVersion": "1.0.0",
         "configurationUpdate": {
           "merge": "{\"pythonVersion\":\"3.7\"}"
         }
       }
     }
   }
   ```  
**Example configuration update with reset and merge updates**  

   Consider an example industrial dashboard component, `com.example.IndustrialDashboard`, that has the following default configuration.

   ```
   {
     "name": null,
     "mode": "REQUEST",
     "network": {
       "useHttps": true,
       "port": {
         "http": 80,
         "https": 443
       },
     },
     "tags": []
   }
   ```

   The following configuration update specifies the following instructions:

   1. Reset the HTTPS setting to its default value (`true`).

   1. Reset the list of industrial tags to an empty list.

   1. Merge a list of industrial tags that identify temperature and pressure data streams for two boilers.

   ```
   {
     "reset": [
       "/network/useHttps",
       "/tags"
     ],
     "merge": {
       "tags": [
         "/boiler/1/temperature",
         "/boiler/1/pressure",
         "/boiler/2/temperature",
         "/boiler/2/pressure"
       ]
     }
   }
   ```

   The following example `components` object specifies to deploy this industrial dashboard component and configuration update.

   ```
   {
     "targetArn": "targetArn",
     "deploymentName": "deploymentName",
     "components": {
       "com.example.IndustrialDashboard": {
         "componentVersion": "1.0.0",
         "configurationUpdate": {
           "reset": [
             "/network/useHttps",
             "/tags"
           ],
           "merge": "{\"tags\":[\"/boiler/1/temperature\",\"/boiler/1/pressure\",\"/boiler/2/temperature\",\"/boiler/2/pressure\"]}"
         }
       }
     }
   }
   ```

1. (Optional) Define deployment policies for the deployment. You can configure when core devices can safely apply a deployment or what to do if a core device fails to apply the deployment. To do so, add a `deploymentPolicies` object to `deployment.json`, and then do any of the following:

   1. (Optional) Specify the component update policy (`componentUpdatePolicy`). This policy defines whether or not the deployment lets components defer an update until they are ready to update. For example, components may need to clean up resources or finish critical actions before they can restart to apply an update. This policy also defines the amount of time that components have to respond to an update notification.

      This policy is an object with the following parameters:
      + `action` – (Optional) Whether or not to notify components and wait for them to report when they're ready to update. Choose from the following options:
        + `NOTIFY_COMPONENTS` – The deployment notifies each component before it stops and updates that component. Components can use the [SubscribeToComponentUpdates](ipc-component-lifecycle.md#ipc-operation-subscribetocomponentupdates) IPC operation to receive these notifications.
        + `SKIP_NOTIFY_COMPONENTS` – The deployment doesn't notify components or wait for them to be safe to update.

        Defaults to `NOTIFY_COMPONENTS`.
      + `timeoutInSeconds` The amount of time in seconds that each component has to respond to an update notification with the [DeferComponentUpdate](ipc-component-lifecycle.md#ipc-operation-defercomponentupdate) IPC operation. If the component doesn't respond within this amount of time, then the deployment proceeds on the core device.

        Defaults to 60 seconds.

   1. (Optional) Specify the configuration validation policy (`configurationValidationPolicy`). This policy defines how long each component has to validate a configuration update from a deployment. Components can use the [SubscribeToValidateConfigurationUpdates](ipc-component-configuration.md#ipc-operation-subscribetovalidateconfigurationupdates) IPC operation to subscribe to notifications for their own configuration updates. Then, components can use the [SendConfigurationValidityReport](ipc-component-configuration.md#ipc-operation-sendconfigurationvalidityreport) IPC operation to tell the AWS IoT Greengrass Core software if the configuration update is valid. If the configuration update isn't valid, the deployment fails.

      This policy is an object with the following parameter:
      + `timeoutInSeconds` (Optional) The amount of time in seconds that each component has to validate a configuration update. If the component doesn't respond within this amount of time, then the deployment proceeds on the core device.

        Defaults to 30 seconds.

   1. (Optional) Specify the failure handling policy (`failureHandlingPolicy`). This policy is a string that defines whether or not to roll back devices if the deployment fails. Choose from the following options:
      + `ROLLBACK` – If the deployment fails on a core device, then the AWS IoT Greengrass Core software rolls back that core device to its previous configuration.
      + `DO_NOTHING` – If the deployment fails on a core device, then the AWS IoT Greengrass Core software keeps the new configuration. This can result in broken components if the new configuration isn't valid.

      Defaults to `ROLLBACK`.

   Your deployment in `deployment.json` may look similar to the following example:

   ```
   {
     "targetArn": "targetArn",
     "deploymentName": "deploymentName",
     "components": {
       "com.example.IndustrialDashboard": {
         "componentVersion": "1.0.0",
         "configurationUpdate": {
           "reset": [
             "/network/useHttps",
             "/tags"
           ],
           "merge": "{\"tags\":[\"/boiler/1/temperature\",\"/boiler/1/pressure\",\"/boiler/2/temperature\",\"/boiler/2/pressure\"]}"
         }
       }
     },
     "deploymentPolicies": {
       "componentUpdatePolicy": {
         "action": "NOTIFY_COMPONENTS",
         "timeoutInSeconds": 30
       },
       "configurationValidationPolicy": {
         "timeoutInSeconds": 60
       },
       "failureHandlingPolicy": "ROLLBACK"
     }
   }
   ```

1. (Optional) Define how the deployment stops, rolls out, or times out. AWS IoT Greengrass uses AWS IoT Core jobs to send deployments to core devices, so these options are identical to the configuration options for AWS IoT Core jobs. For more information, see [Job rollout and abort configuration](https://docs.aws.amazon.com/iot/latest/developerguide/job-rollout-abort.html) in the *AWS IoT Developer Guide*.

   To define the job options, add an `iotJobConfiguration` object to `deployment.json`. Then, define the options to configure.

   Your deployment in `deployment.json` may look similar to the following example:

   ```
   {
     "targetArn": "targetArn",
     "deploymentName": "deploymentName",
     "components": {
       "com.example.IndustrialDashboard": {
         "componentVersion": "1.0.0",
         "configurationUpdate": {
           "reset": [
             "/network/useHttps",
             "/tags"
           ],
           "merge": "{\"tags\":[\"/boiler/1/temperature\",\"/boiler/1/pressure\",\"/boiler/2/temperature\",\"/boiler/2/pressure\"]}"
         }
       }
     },
     "deploymentPolicies": {
       "componentUpdatePolicy": {
         "action": "NOTIFY_COMPONENTS",
         "timeoutInSeconds": 30
       },
       "configurationValidationPolicy": {
         "timeoutInSeconds": 60
       },
       "failureHandlingPolicy": "ROLLBACK"
     },
     "iotJobConfiguration": {
       "abortConfig": {
         "criteriaList": [
           {
             "action": "CANCEL",
             "failureType": "ALL",
             "minNumberOfExecutedThings": 100,
             "thresholdPercentage": 5
           }
         ]
       },
       "jobExecutionsRolloutConfig": {
         "exponentialRate": {
           "baseRatePerMinute": 5,
           "incrementFactor": 2,
           "rateIncreaseCriteria": {
             "numberOfNotifiedThings": 10,
             "numberOfSucceededThings": 5
           }
         },
         "maximumPerMinute": 50
       },
       "timeoutConfig":  {
         "inProgressTimeoutInMinutes": 5
       }
     }
   }
   ```

1. (Optional) Add tags (`tags`) for the deployment. For more information, see [Tag your AWS IoT Greengrass Version 2 resources](tag-resources.md).

1. Run the following command to create the deployment from `deployment.json`.

   ```
   aws greengrassv2 create-deployment --cli-input-json file://deployment.json
   ```

   <a name="check-new-deployment-status"></a>The response includes a `deploymentId` that identifies this deployment. You can use the deployment ID to check the status of the deployment. For more information, see [Check deployment status](check-deployment-status.md#check-cloud-deployment-status).

# Update component configurations


Component configurations are JSON objects that define the parameters for each component. Each component's recipe defines its default configuration, which you modify when you deploy components to core devices.

When you create a deployment, you can specify the *configuration update* to apply for each component. Configuration updates are patch operations, which means that the update modifies the component configuration that exists on the core device. If the core device doesn't have the component, then the configuration update modifies and applies the default configuration for that deployment.

The configuration update defines *reset* updates and *merge* updates. Reset updates define which configuration values to reset to their defaults or remove. Merge updates define the new configuration values to set for the component. When you deploy a configuration update, the AWS IoT Greengrass Core software runs the reset update before the merge update.

Components can validate the configuration updates that you deploy. The component subscribes to receive a notification when a deployment changes its configuration, and it can reject a configuration that it doesn't support. For more information, see [Interact with component configuration](ipc-component-configuration.md).

**Topics**
+ [

## Reset updates
](#reset-configuration-update)
+ [

## Merge updates
](#merge-configuration-update)
+ [

## Examples
](#configuration-update-example)

## Reset updates


Reset updates define which configuration values to reset to their default values on the core device. If a configuration value doesn't have a default value, then the reset update removes that value from the component's configuration. This can help you fix a component that breaks as the result of an invalid configuration.

Use a list of JSON pointers to define which configuration values to reset. JSON pointers start with a forward slash `/`. To identify a value in a nested component configuration, use forward slashes (`/`) to separate the keys for each level in the configuration. For more information, see the [JSON pointer specification](https://tools.ietf.org/html/rfc6901).

**Note**  
You can reset only an entire list to its default values. You can't use reset updates to reset an individual element in a list. 

To reset a component's entire configuration to its default values, specify a single empty string as the reset update.

```
"reset": [""]
```

## Merge updates


Merge updates define the configuration values to insert into the component configuration on the core. The merge update is a JSON object that the AWS IoT Greengrass Core software merges after it resets the values in the paths that you specify in the reset update. When you use the AWS CLI or AWS SDKs, you must serialize this JSON object as a string.

You can merge a key-value pair that doesn't exist in the component's default configuration. You can also merge a key-value pair that has a different type than the value with the same key. The new value replaces the old value. This means that you can change the configuration object's structure.

You can merge null values and empty strings, lists, and objects.

**Note**  
You can't use merge updates for the purpose of inserting or appending an element to a list. You can replace an entire list, or you can define an object where each element has a unique key.  
<a name="configuration-value-type-note"></a>AWS IoT Greengrass uses JSON for configuration values. JSON specifies a number type but doesn't differentiate between integers and floats. As a result, configuration values might convert to floats in AWS IoT Greengrass. To ensure that your component uses the correct data type, we recommend that you define numeric configuration values as strings. Then, have your component parse them as integers or floats. This ensures that your configuration values have the same type in the configuration and on your core device.

### Use recipe variables in merge updates


This feature is available for v2.6.0 and later of the [Greengrass nucleus component](greengrass-nucleus-component.md).

If you set the Greengrass nucleus' [interpolateComponentConfiguration](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-interpolate-component-configuration) configuration option to `true`, you can use recipe variables, other than the `component_dependency_name:configuration:json_pointer` recipe variable, in merge updates. For example, you can use the `{iot:thingName}` recipe variable in a merge update to include the core device's AWS IoT thing name in a component configuration value, such as an [interprocess communication (IPC) authorization policy](interprocess-communication.md#ipc-authorization-policies).

## Examples


The following example demonstrates configuration updates for a dashboard component that has the following default configuration. This example component displays information about industrial equipment.

```
{
  "name": null,
  "mode": "REQUEST",
  "network": {
    "useHttps": true,
    "port": {
      "http": 80,
      "https": 443
    },
  },
  "tags": []
}
```

### Industrial dashboard component recipe


------
#### [ JSON ]

```
{
  "RecipeFormatVersion": "2020-01-25",
  "ComponentName": "com.example.IndustrialDashboard",
  "ComponentVersion": "1.0.0",
  "ComponentDescription": "Displays information about industrial equipment.",
  "ComponentPublisher": "Amazon",
  "ComponentConfiguration": {
    "DefaultConfiguration": {
      "name": null,
      "mode": "REQUEST",
      "network": {
        "useHttps": true,
        "port": {
          "http": 80,
          "https": 443
        },
      },
      "tags": []
    }
  },
  "Manifests": [
    {
      "Platform": {
        "os": "linux"
      },
      "Lifecycle": {
        "Run": "python3 -u {artifacts:path}/industrial_dashboard.py"
      }
    },
    {
      "Platform": {
        "os": "windows"
      },
      "Lifecycle": {
        "Run": "py -3 -u {artifacts:path}/industrial_dashboard.py"
      }
    }
  ]
}
```

------
#### [ YAML ]

```
---
RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.IndustrialDashboard
ComponentVersion: '1.0.0'
ComponentDescription: Displays information about industrial equipment.
ComponentPublisher: Amazon
ComponentConfiguration:
  DefaultConfiguration:
    name: null
    mode: REQUEST
    network:
      useHttps: true
      port:
        http: 80
        https: 443
    tags: []
Manifests:
  - Platform:
      os: linux
    Lifecycle:
      Run: |
        python3 -u {artifacts:path}/industrial_dashboard.py
  - Platform:
      os: windows
    Lifecycle:
      Run: |
        py -3 -u {artifacts:path}/industrial_dashboard.py
```

------

**Example 1: Merge update**  
You create a deployment that applies the following configuration update, which specifies a merge update but not a reset update. This configuration update tells the component to display the dashboard on HTTP port 8080 with data from two boilers.    
**Configuration to merge**  

```
{
  "name": "Factory 2A",
  "network": {
    "useHttps": false,
    "port": {
      "http": 8080
    }
  },
  "tags": [
    "/boiler/1/temperature",
    "/boiler/1/pressure",
    "/boiler/2/temperature",
    "/boiler/2/pressure"
  ]
}
```
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": {
    "com.example.IndustrialDashboard": {
      "componentVersion": "1.0.0",
      "configurationUpdate": {
        "merge": "{\"name\":\"Factory 2A\",\"network\":{\"useHttps\":false,\"port\":{\"http\":8080}},\"tags\":[\"/boiler/1/temperature\",\"/boiler/1/pressure\",\"/boiler/2/temperature\",\"/boiler/2/pressure\"]}"
      }
    }
  }
}
```
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 "com.example.IndustrialDashboard=1.0.0" \
  --update-config dashboard-configuration.json
```
The `dashboard-configuration.json` file contains the following JSON document.  

```
{
  "com.example.IndustrialDashboard": {
    "MERGE": {
      "name": "Factory 2A",
      "network": {
        "useHttps": false,
        "port": {
          "http": 8080
        }
      },
      "tags": [
        "/boiler/1/temperature",
        "/boiler/1/pressure",
        "/boiler/2/temperature",
        "/boiler/2/pressure"
      ]
    }
  }
}
```
After this update, the dashboard component has the following configuration.  

```
{
  "name": "Factory 2A",
  "mode": "REQUEST",
  "network": {
    "useHttps": false,
    "port": {
      "http": 8080,
      "https": 443
    }
  },
  "tags": [
    "/boiler/1/temperature",
    "/boiler/1/pressure",
    "/boiler/2/temperature",
    "/boiler/2/pressure"
  ]
}
```

**Example 2: Reset and merge updates**  
Then, you create a deployment that applies the following configuration update, which specifies a reset update and a merge update. These updates specify to display the dashboard on the default HTTPS port with data from different boilers. These updates modify the configuration that results from the configuration updates in the previous example.    
**Reset paths**  

```
[
  "/network/useHttps",
  "/tags"
]
```  
**Configuration to merge**  

```
{
  "tags": [
    "/boiler/3/temperature",
    "/boiler/3/pressure",
    "/boiler/4/temperature",
    "/boiler/4/pressure"
  ]
}
```
The following command creates a deployment to a core device.  

```
aws greengrassv2 create-deployment --cli-input-json file://dashboard-deployment2.json
```
The `dashboard-deployment2.json` file contains the following JSON document.  

```
{
  "targetArn": "arn:aws:iot:us-west-2:123456789012:thing/MyGreengrassCore",
  "deploymentName": "Deployment for MyGreengrassCore",
  "components": {
    "com.example.IndustrialDashboard": {
      "componentVersion": "1.0.0",
      "configurationUpdate": {
        "reset": [
          "/network/useHttps",
          "/tags"
        ],
        "merge": "{\"tags\":[\"/boiler/3/temperature\",\"/boiler/3/pressure\",\"/boiler/4/temperature\",\"/boiler/4/pressure\"]}"
      }
    }
  }
}
```
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 "com.example.IndustrialDashboard=1.0.0" \
  --update-config dashboard-configuration2.json
```
The `dashboard-configuration2.json` file contains the following JSON document.  

```
{
  "com.example.IndustrialDashboard": {
    "RESET": [
      "/network/useHttps",
      "/tags"
    ],
    "MERGE": {
      "tags": [
        "/boiler/3/temperature",
        "/boiler/3/pressure",
        "/boiler/4/temperature",
        "/boiler/4/pressure"
      ]
    }
  }
}
```
After this update, the dashboard component has the following configuration.  

```
{
  "name": "Factory 2A",
  "mode": "REQUEST",
  "network": {
    "useHttps": true,
    "port": {
      "http": 8080,
      "https": 443
    }
  },
  "tags": [
    "/boiler/3/temperature",
    "/boiler/3/pressure",
    "/boiler/4/temperature",
    "/boiler/4/pressure",
  ]
}
```

# Create subdeployments


**Note**  
The subdeployment feature is available on Greengrass nucleus version 2.9.0 and later. It is not possible to deploy a configuration to a subdeployment with earlier component versions of Greengrass nucleus.

A subdeployment is a deployment that targets a smaller subset of devices within a parent deployment. You can use subdeployments to deploy a configuration to a smaller subset of devices. You can also create subdeployments to retry an unsuccessful parent deployment when one or more devices in that parent deployment fails. With this feature, you can select devices that failed in that parent deployment and create a subdeployment to test configurations until the subdeployment is successful. Once the subdeployment is successful, you can redeploy that configuration to the parent deployment.

Follow the steps in this section to create a subdeployment and check its status. For more information about how to create deployments, see [Create deployments](https://docs.aws.amazon.com/greengrass/v2/developerguide/create-deployments.html).

**To create a subdeployment (AWS CLI)**

1. <a name="create-subdeployments-step1"></a>Run the following command to retrieve the latest deployments for a thing group. Replace the ARN in the command with the ARN of the thing group to query. Set `--history-filter` to **LATEST\$1ONLY** to see the latest deployment of that thing group.

   ```
   aws greengrassv2 list-deployments --target-arn arn:aws:iot:region:account-id:thinggroup/thingGroupName --history-filter LATEST_ONLY
   ```

1. Copy the `deploymentId` from the response to the **list-deployments** command to use in the next step.

1. Run the following command to retrieve the status of a deployment. Replace `deploymentId` with the ID of the deployment to query.

   ```
   aws greengrassv2 get-deployment --deployment-id deploymentId
   ```

1. Copy the `iotJobId` from the response to the **get-deployment** command to use in the following step.

1. Run the following command to retrieve the list of job executions for the specified job. Replace *jobID* with the `iotJobId` from the previous step. Replace *status* with the status you want to filter for. You can filter results with the following statuses:
   + `QUEUED`
   + `IN_PROGRESS`
   + `SUCCEEDED`
   + `FAILED`
   + `TIMED_OUT`
   + `REJECTED`
   + `REMOVED`
   + `CANCELED`

   ```
   aws iot list-job-executions-for-job --job-id jobID --status status
   ```

1. Create a new AWS IoT thing group, or use an existing thing group, for your subdeployment. Then, add an AWS IoT thing to this thing group. You use thing groups to manage fleets of Greengrass core devices. When you deploy software components to your devices, you can target either individual devices or groups of devices. You can add a device to a thing group with an active Greengrass deployment. Once added, you can then deploy that thing group's software components to that device.

   To create a new thing group and add your devices to it, do the following:

   1. Create an AWS IoT thing group. Replace *MyGreengrassCoreGroup* with the name for the new thing group. You can't use a colon (:) in a thing group name.
**Note**  
If a thing group for a subdeployment is used with one `parentTargetArn`, it can't be reused with a different parent fleet. If a thing group has already been used to create a subdeployment for another fleet, the API will return an error.

      ```
      aws iot create-thing-group --thing-group-name MyGreengrassCoreGroup
      ```

      If the request succeeds, the response looks similar to the following example:

      ```
      {
        "thingGroupName": "MyGreengrassCoreGroup",
        "thingGroupArn": "arn:aws:iot:us-west-2:123456789012:thinggroup/MyGreengrassCoreGroup",
        "thingGroupId": "4df721e1-ff9f-4f97-92dd-02db4e3f03aa"
      }
      ```

   1. Add a provisioned Greengrass core to your thing group. Run the following command with these parameters:
      + Replace *MyGreengrassCore* with the name of your provisioned Greengrass core.
      + Replace *MyGreengrassCoreGroup* with the name of your 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.

1. Create a file called `deployment.json`, and then copy the following JSON object into the file. Replace *targetArn* with the ARN of the AWS IoT thing group to target for the subdeployment. A subdeployment target can only be a thing group. Thing group ARNs have the following format:
   + **Thing group** – `arn:aws:iot:region:account-id:thinggroup/thingGroupName`

   ```
   {
     "targetArn": "targetArn"
   }
   ```

1. Run the following command again to get the original deployment's details. These details include metadata, components, and job configuration. Replace *deploymentId* with the ID from [Step 1](#create-subdeployments-step1). You can use this deployment configuration to configure your subdeployment and make changes as needed.

   ```
   aws greengrassv2 get-deployment --deployment-id deploymentId
   ```

   The response contains the deployment's details. Copy any of the following key-value pairs from the **get-deployment** command's response into `deployment.json`. You can change these values for the subdeployment. For more information about the details of this command, see [GetDeployment](https://docs.aws.amazon.com/greengrass/v2/APIReference/API_GetDeployment.html).
   + `components` – The deployment's components. To uninstall a component, remove it from this object.
   + `deploymentName` – The deployment's name.
   + `deploymentPolicies` – The deployment's policies.
   + `iotJobConfiguration` – The deployment's job configuration.
   + `parentTargetArn` – The target of the parent deployment.
   + `tags` – The deployment's tags.

1. Run the following command to create the subdeployment from `deployment.json`. Replace *subdeploymentName* with a name for the subdeployment.

   ```
   aws greengrassv2 create-deployment --deployment-name subdeploymentName --cli-input-json file://deployment.json
   ```

   The response includes a `deploymentId` that identifies this subdeployment. You can use the deployment ID to check the status of the deployment. For more information, see [Check deployment status](https://docs.aws.amazon.com/greengrass/v2/developerguide/check-deployment-status.html#check-cloud-deployment-status).

1. If the subdeployment is successful, you can use its configuration to revise the parent deployent. Copy the `deployment.json` that you used in the previous step. Replace the `targetArn` in the JSON file with the parent deployment's ARN and run the following command to create the parent deployment using this new configuration.
**Note**  
If you create a new deployment revision of the parent fleet, it replaces all deployment revisions and subdeployments for that parent deployment. For more information, see [Revise deployments](https://docs.aws.amazon.com/greengrass/v2/developerguide/revise-deployments.html).

   ```
   aws greengrassv2 create-deployment --cli-input-json file://deployment.json
   ```

   <a name="check-new-deployment-status"></a>The response includes a `deploymentId` that identifies this deployment. You can use the deployment ID to check the status of the deployment. For more information, see [Check deployment status](check-deployment-status.md#check-cloud-deployment-status).

# Revise deployments


Each target thing or thing group can have one active deployment at a time. When you create a deployment for a target that already has a deployment, the software components in the new deployment replace those from the previous deployment. If the new deployment doesn't define a component that the previous deployment defines, the AWS IoT Greengrass Core software removes that component from the target core devices. You can revise an existing deployment so that you don't remove the components that run on core devices from a previous deployment to a target.

To revise a deployment, you create a deployment that starts from the same components and configurations that exist in a previous deployment. You use the [CreateDeployment](https://docs.aws.amazon.com/greengrass/v2/APIReference/API_CreateDeployment.html) operation, which is the same operation that you use to [create deployments](create-deployments.md).

**To revise a deployment (AWS CLI)**

1. <a name="revise-deployment-list-deployments-intro"></a>Run the following command to list the deployments for the deployment target. Replace *targetArn* with the ARN of the target AWS IoT thing or thing group.

   ```
   aws greengrassv2 list-deployments --target-arn targetArn
   ```

   The response contains a list with the latest deployment for the target. Copy the `deploymentId` from the response to use in the next step.
**Note**  <a name="revise-deployment-list-deployments-revision-note"></a>
You can also revise a deployment other than the latest revision for the target. Specify the `--history-filter ALL` argument to list all deployments for the target. Then, copy the ID of the deployment that you want to revise.

1. <a name="revise-deployment-get-deployment"></a>Run the following command to get the deployment's details. These details include metadata, components, and job configuration. Replace *deploymentId* with the ID from the previous step.

   ```
   aws greengrassv2 get-deployment --deployment-id deploymentId
   ```

   The response contains the deployment's details.

1. Create a file called `deployment.json` and copy the previous command's response into the file.

1. Remove the following key-value pairs from the JSON object in `deployment.json`:
   + `deploymentId`
   + `revisionId`
   + `iotJobId`
   + `iotJobArn`
   + `creationTimestamp`
   + `isLatestForTarget`
   + `deploymentStatus`

   The [CreateDeployment](https://docs.aws.amazon.com/greengrass/v2/APIReference/API_CreateDeployment.html) operation expects a payload with the following structure.

   ```
   {
     "targetArn": "String",
     "components": Map of components,
     "deploymentPolicies": DeploymentPolicies,
     "iotJobConfiguration": DeploymentIoTJobConfiguration,
     "tags": Map of tags
   }
   ```

1. In `deployment.json`, do any of the following:
   + Change the deployment's name (`deploymentName`).
   + Change the deployment's components (`components`).
   + Change the deployment's policies (`deploymentPolicies`).
   + Change the deployment's job configuration (`iotJobConfiguration`).
   + Change the deployment's tags (`tags`).

   For more information about how to define these deployment details, see [Create deployments](create-deployments.md).

1. Run the following command to create the deployment from `deployment.json`.

   ```
   aws greengrassv2 create-deployment --cli-input-json file://deployment.json
   ```

   <a name="check-new-deployment-status"></a>The response includes a `deploymentId` that identifies this deployment. You can use the deployment ID to check the status of the deployment. For more information, see [Check deployment status](check-deployment-status.md#check-cloud-deployment-status).

# Cancel deployments


You can cancel an active deployment to prevent its software components from installing on AWS IoT Greengrass core devices. If you cancel a deployment that targets a thing group, core devices that you add to the group won't receive that continuous deployment. If a core device already runs the deployment, you won't change the components on that device when you cancel the deployment. You must [create a new deployment](create-deployments.md) or [revise the deployment](revise-deployments.md) to modify the components that run on the core devices that received the canceled deployment.

**To cancel a deployment (AWS CLI)**

1. Run the following command to find the ID of the latest deployment revision for a target. The latest revision is the only deployment that can be active for a target, because previous deployments cancel when you create a new revision. Replace *targetArn* with the ARN of the target AWS IoT thing or thing group.

   ```
   aws greengrassv2 list-deployments --target-arn targetArn
   ```

   The response contains a list with the latest deployment for the target. Copy the `deploymentId` from the response to use in the next step.

1. Run the following command to cancel the deployment. Replace *deploymentId* with the ID from the previous step.

   ```
   aws greengrassv2 cancel-deployment --deployment-id deploymentId
   ```

   If the operation succeeds, the deployment status changes to `CANCELED`.

# Check deployment status


You can check the status of a deployment that you create in AWS IoT Greengrass. You can also check the status of the AWS IoT jobs that roll out the deployment to each core device. While a deployment is active, the AWS IoT job's status is `IN_PROGRESS`. After you create a new revision of a deployment, the status of the previous revision's AWS IoT job changes to `CANCELLED`.

**Topics**
+ [

## Check deployment status
](#check-cloud-deployment-status)
+ [

## Check device deployment status
](#check-device-deployment-status)

## Check deployment status


You can check the status of a deployment that you identify by its target or its ID.

**To check deployment status by target (AWS CLI)**
+ Run the following command to retrieve the status of the latest deployment for a target. Replace *targetArn* with the Amazon Resource Name (ARN) of the AWS IoT thing or thing group that the deployment targets.

  ```
  aws greengrassv2 list-deployments --target-arn targetArn
  ```

  The response contains a list with the latest deployment for the target. This deployment object includes the status of the deployment.

**To check deployment status by ID (AWS CLI)**
+ Run the following command to retrieve the status of a deployment. Replace *deploymentId* with the ID of the deployment to query.

  ```
  aws greengrassv2 get-deployment --deployment-id deploymentId
  ```

  The response contains the status of the deployment.

## Check device deployment status


You can check the status of a deployment job that applies to an individual core device. You can also check the status of a deployment job for a thing group deployment.

**To check deployment job statuses for a core device (AWS CLI)**
+ Run the following command to retrieve the status of all deployment jobs for a core device. Replace *coreDeviceName* with the name of the core device to query.

  ```
  aws greengrassv2 list-effective-deployments --core-device-thing-name coreDeviceName
  ```

  The response contains the list of deployment jobs for the core device. You can identify the job for a deployment by the job's `deploymentId` or `targetArn`. Each deployment job contains the status of the job on the core device.

**To check deployment statuses for a thing group (AWS CLI)**

1. Run the following command to retrieve the ID of an existing deployment. Replace *targetArn* with the ARN of the target thing group.

   ```
   aws greengrassv2 list-deployments --target-arn targetArn
   ```

   The response contains a list with the latest deployment for the target. Copy the `deploymentId` from the response to use in the next step.
**Note**  
You can also list a deployment other than the latest deployment for the target. Specify the `--history-filter ALL` argument to list all deployments for the target. Then, copy the ID of the deployment that you want to check the status of.

1. Run the following command to get the deployment's details. Replace *deploymentID* with the ID from the previous step.

   ```
   aws greengrassv2 get-deployment --deployment-id deploymentId
   ```

   The response contains information about the deployment. Copy the `iotJobId` from the response to use in the following step.

1. Run the following command to describe a core device's job execution for the deployment. Replace *iotJobId* and *coreDeviceThingName* with the job ID from the previous step and the core device you want to check the status for.

   ```
   aws iot describe-job-execution --job-id iotJobId --thing-name coreDeviceThingName
   ```

   The response contains the status of the core device's deployment job execution and details about the status. The `detailsMap` contains the following information:
   + `detailed-deployment-status` – The deployment result status, which can be one of the following values:
     + `SUCCESSFUL` – The deployment succeeded.
     + `FAILED_NO_STATE_CHANGE` – The deployment failed while the core device prepared to apply the deployment.
     + `FAILED_ROLLBACK_NOT_REQUESTED` – The deployment failed, and the deployment didn't specify to roll back to a previous working configuration, so the core device might not be functioning correctly.
     + `FAILED_ROLLBACK_COMPLETE` – The deployment failed, and the core device successfully rolled back to a previous working configuration.
     + `FAILED_UNABLE_TO_ROLLBACK` – The deployment failed, and the core device failed to roll back to a previous working configuration, so the core device might not be functioning correctly.

     If the deployment failed, check the `deployment-failure-cause` value and the core device's log files to identify the issue. For more information about how to access the core device's log files, see [Monitor AWS IoT Greengrass logs](monitor-logs.md).
   + `deployment-failure-cause` – An error message that provides additional details about why the job execution failed.

   The response looks similar to the following example.

   ```
   {
     "execution": {
       "jobId": "2cc2698a-5175-48bb-adf2-1dd345606ebd",
       "status": "FAILED",
       "statusDetails": {
         "detailsMap": {
           "deployment-failure-cause": "No local or cloud component version satisfies the requirements. Check whether the version constraints conflict and that the component exists in your AWS account with a version that matches the version constraints. If the version constraints conflict, revise deployments to resolve the conflict. Component com.example.HelloWorld version constraints: LOCAL_DEPLOYMENT requires =1.0.0, thinggroup/MyGreengrassCoreGroup requires =1.0.1.",
           "detailed-deployment-status": "FAILED_NO_STATE_CHANGE"
         }
       },
       "thingArn": "arn:aws:iot:us-west-2:123456789012:thing/MyGreengrassCore",
       "queuedAt": "2022-02-15T14:45:53.098000-08:00",
       "startedAt": "2022-02-15T14:46:05.670000-08:00",
       "lastUpdatedAt": "2022-02-15T14:46:20.892000-08:00",
       "executionNumber": 1,
       "versionNumber": 3
     }
   }
   ```