# AWS-provided components
<a name="public-components"></a>

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 support | 
| --- | --- | --- | --- | --- | --- | 
| [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 | Built-in | 
| [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) | Built-in | 
| [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 | Built-in | 
| [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
<a name="greengrass-nucleus-component"></a>

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
<a name="greengrass-nucleus-component-versions"></a>

This component has the following versions:
+ 2.17.x
+ 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
<a name="greengrass-v2-requirements"></a>

**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 can run the AWS IoT Greengrass Core software as a root user. Use `sudo`, for example. You can also run the AWS IoT Greengrass Core software as a non-root user. For more information, see [Set up AWS IoT Greengrass V2 core devices as non-root](setup-greengrass-non-root.md).
+ 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
<a name="greengrass-v2-supported-platforms"></a>

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
<a name="greengrass-v2-windows-feature-considerations"></a>

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
<a name="greengrass-nucleus-component-os-support"></a>

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
<a name="greengrass-nucleus-component-requirements"></a>

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
<a name="greengrass-nucleus-component-dependencies"></a>

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
<a name="greengrass-nucleus-component-install"></a>

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
<a name="greengrass-nucleus-component-configuration"></a>

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
<a name="greengrass-nucleus-component-log-file"></a>

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
<a name="greengrass-nucleus-component-changelog"></a>

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


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.17.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-component.html)  | 
|  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
<a name="greengrass-nucleus-lite-component"></a>

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
<a name="greengrass-nucleus-lite-component-versions"></a>

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

## Operating system
<a name="greengrass-nucleus-lite-component-os-support"></a>

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
<a name="greengrass-nucleus-lite-component-requirements"></a>

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.

To run AWS IoT Greengrass nucleus lite as a non-root user, you can use a rootless container. For more information, see [Using Podman](https://github.com/aws-greengrass/aws-greengrass-lite/blob/main/docs/BUILD.md#optional-using-podman) in the AWS IoT Greengrass nucleus lite GitHub repository.

## Compatibility
<a name="greengrass-nucleus-lite-component-compatibility"></a>

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
<a name="greengrass-nucleus-lite-component-install"></a>

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
<a name="greengrass-nucleus-lite-component-configuration"></a>

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
<a name="greengrass-nucleus-lite-component-log-file"></a>

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

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

## Changelog
<a name="greengrass-nucleus-lite-component-changelog"></a>


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.5.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-lite-component.html)  | 
|  2.4.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-lite-component.html)  | 
|  2.3.3  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-nucleus-lite-component.html)  | 
|  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
<a name="client-device-auth-component"></a>

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
<a name="client-device-auth-component-versions"></a>

**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="client-device-auth-component-type"></a>

<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
<a name="client-device-auth-component-os-support"></a>

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

## Requirements
<a name="client-device-auth-component-requirements"></a>

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
<a name="client-device-auth-component-endpoints"></a>

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
<a name="client-device-auth-component-dependencies"></a>

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
<a name="client-device-auth-component-configuration"></a>

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
<a name="client-device-auth-component-log-file"></a>

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
<a name="client-device-auth-component-changelog"></a>

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


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.5.6  |  Updates the component version for the Greengrass nucleus version 2.17.0 release.  | 
|  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
<a name="cloudwatch-metrics-component"></a>

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
<a name="cloudwatch-metrics-component-versions"></a>

This component has the following versions:
+ 4.0.x
+ 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
<a name="cloudwatch-metrics-component-type"></a>

------
#### [ v4.x - 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
<a name="cloudwatch-metrics-component-os-support"></a>

------
#### [ v4.x - 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
<a name="cloudwatch-metrics-component-requirements"></a>

This component has the following requirements:

------
#### [ v4.x - 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.
+ The following Python libraries, including any dependencies, must be installed and available to the user running the component:
  + [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/)
**Note**  
You can set the `UseInstaller` configuration to `true` to install these libraries automatically into the provided Python environment.
+ 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
<a name="cloudwatch-metrics-component-endpoints"></a>

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
<a name="cloudwatch-metrics-component-dependencies"></a>

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.

------
#### [ 4.0.0 - 3.0.0 ]

The following table lists the dependencies for versions 4.0.0 to 3.0.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
<a name="cloudwatch-metrics-component-configuration"></a>

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

------
#### [ v4.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 to install this component's Python dependencies into the provided Python environment.  
Set this value to `true` to automatically install this component's Python dependencies. When set to `false`, you must install the following libraries, including any dependencies, and make them available to the Python environment provided to the user running the component.  
+ [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: `false`

`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
}
```

------
#### [ 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 to install this component's Python dependencies into the provided Python environment.  
Set this value to `false` to use a custom script or manually install dependencies. When set to `false`, you must install the following libraries, including any dependencies, and make them available to the Python environment provided to the user running the component.  
+ [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
<a name="cloudwatch-metrics-component-input-data"></a>

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="cloudwatch-metrics-component-output-data"></a>

 <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
<a name="cloudwatch-metrics-component-licenses"></a>

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
<a name="cloudwatch-metrics-component-log-file"></a>

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
<a name="cloudwatch-metrics-component-changelog"></a>

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

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


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  4.0.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/cloudwatch-metrics-component.html)  | 
|  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
<a name="cloudwatch-metrics-component-see-also"></a>
+ [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
<a name="device-defender-component"></a>

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
<a name="device-defender-component-versions"></a>

This component has the following versions:
+ 4.0.x
+ 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
<a name="device-defender-component-type"></a>

------
#### [ v4.x - 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
<a name="device-defender-component-os-support"></a>

------
#### [ v4.x - 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
<a name="device-defender-component-requirements"></a>

This component has the following requirements:

------
#### [ v4.x - 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.
+ The following Python libraries, including any dependencies, must be installed and available to the user running the component:
  + [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.
**Note**  
You can set the `UseInstaller` configuration to `true` to install these libraries automatically into the provided Python environment.
+ 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
<a name="device-defender-component-dependencies"></a>

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.

------
#### [ 4.0.0 - 3.0.0 ]

The following table lists the dependencies for versions 4.0.0 to 3.0.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.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
<a name="device-defender-component-configuration"></a>

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

------
#### [ v4.x ]

`PublishRetryCount`  
The amount of times the publish will be retried.  
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 to install this component's Python dependencies into the provided Python environment.  
Set this value to `true` to automatically install this component's Python dependencies. When set to `false`, you must install the following libraries, including any dependencies, and make them available to the Python environment provided to the user running the component.  
+ [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.
Default: `false`

------
#### [ 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 to install this component's Python dependencies into the provided Python environment.  
Set this value to `false` to use a custom script or manually install dependencies. When set to `false`, you must install the following libraries, including any dependencies, and make them available to the Python environment provided to the user running the component.  
+ [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
<a name="device-defender-component-input-data"></a>

This component doesn't accept messages as input data.

## Output data
<a name="device-defender-component-output-data"></a>

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
<a name="device-defender-component-log-file"></a>

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="device-defender-component-licenses"></a>

<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
<a name="device-defender-component-changelog"></a>

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

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


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  4.0.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/device-defender-component.html)  | 
|  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
<a name="disk-spooler-component"></a>

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
<a name="disk-spooler-component-versions"></a>

This component has the following versions:
+ 1.0.x

## Type
<a name="disk-spooler-component-type"></a>

<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
<a name="disk-spooler-component-os-support"></a>

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

## Requirements
<a name="disk-spooler-component-requirements"></a>

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
<a name="disk-spooler-component-dependencies"></a>

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
<a name="disk-spooler-component-usage"></a>

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
<a name="disk-spooler-component-log-file"></a>

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
<a name="disk-spooler-component-changelog"></a>

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


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  1.0.8  |  Updates the component version for the Greengrass nucleus version 2.17.0 release.  | 
|  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
<a name="docker-application-manager-component"></a>

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
<a name="docker-application-manager-component-versions"></a>

This component has the following versions:
+ 2.0.x

## Type
<a name="docker-application-manager-component-type"></a>

<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
<a name="docker-application-manager-component-os-support"></a>

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

## Requirements
<a name="docker-application-manager-component-requirements"></a>

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
<a name="docker-application-manager-component-endpoints"></a>

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
<a name="docker-application-manager-component-dependencies"></a>

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
<a name="docker-application-manager-component-configuration"></a>

This component doesn't have any configuration parameters.

## Local log file
<a name="docker-application-manager-component-log-file"></a>

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
<a name="docker-application-manager-component-changelog"></a>

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


|   **Version**   |   **Changes**   | 
| --- | --- | 
|  2.0.16  |  Updates the component version for the Greengrass nucleus version 2.17.0 release.  | 
|  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
<a name="docker-application-manager-component-see-also"></a>
+  [Run a Docker container](run-docker-container.md) 

# Edge connector for Kinesis Video Streams
<a name="kvs-edge-connector-component"></a>

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
<a name="kvs-edge-connector-component-versions"></a>

This component has the following versions:
+ 1.0.x

## Type
<a name="kvs-edge-connector-component-type"></a>

<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
<a name="kvs-edge-connector-component-os-support"></a>

This component can be installed on Linux core devices only.

## Requirements
<a name="kvs-edge-connector-component-requirements"></a>

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
<a name="kvs-edge-connector-component-endpoints"></a>

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
<a name="kvs-edge-connector-component-dependencies"></a>

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
<a name="kvs-edge-connector-component-configuration"></a>

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
<a name="kvs-edge-connector-component-licenses"></a>

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
<a name="kvs-edge-connector-component-usage"></a>

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
<a name="kvs-edge-connector-component-log-file"></a>

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
<a name="kvs-edge-connector-component-changelog"></a>

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
<a name="kvs-edge-connector-component-see-also"></a>
+ [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
<a name="greengrass-cli-component"></a>

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
<a name="greengrass-cli-component-versions"></a>

This component has the following versions:
+ 2.17.x
+ 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="greengrass-cli-component-type"></a>

<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
<a name="greengrass-cli-component-os-support"></a>

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

## Requirements
<a name="greengrass-cli-component-requirements"></a>

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
<a name="greengrass-cli-component-dependencies"></a>

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
<a name="greengrass-cli-component-configuration"></a>

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
<a name="greengrass-cli-component-log-file"></a>

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
<a name="greengrass-cli-component-changelog"></a>

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


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.17.0  |  Updates the component version for the Greengrass nucleus version 2.17.0 release.  | 
|  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
<a name="ip-detector-component"></a>

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
<a name="ip-detector-component-versions"></a>

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

## Type
<a name="ip-detector-component-type"></a>

<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
<a name="ip-detector-component-os-support"></a>

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

## Requirements
<a name="ip-detector-component-requirements"></a>

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
<a name="ip-detector-component-dependencies"></a>

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
<a name="ip-detector-component-configuration"></a>

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
<a name="ip-detector-component-log-file"></a>

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
<a name="ip-detector-component-changelog"></a>

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


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.2.4  |  Updates the component version for the Greengrass nucleus version 2.17.0 release.  | 
|  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
<a name="kinesis-firehose-component"></a>

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
<a name="kinesis-firehose-component-versions"></a>

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

## Type
<a name="kinesis-firehose-component-type"></a>

<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
<a name="kinesis-firehose-component-os-support"></a>

This component can be installed on Linux core devices only.

## Requirements
<a name="kinesis-firehose-component-requirements"></a>

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
<a name="kinesis-firehose-component-endpoints"></a>

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
<a name="kinesis-firehose-component-dependencies"></a>

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
<a name="kinesis-firehose-component-configuration"></a>

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
<a name="kinesis-firehose-component-input-data"></a>

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="kinesis-firehose-component-output-data"></a>

 <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
<a name="kinesis-firehose-component-log-file"></a>

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
<a name="kinesis-firehose-component-licenses"></a>

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
<a name="kinesis-firehose-component-changelog"></a>

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
<a name="kinesis-firehose-component-see-also"></a>
+ [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
<a name="lambda-launcher-component"></a>

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
<a name="lambda-launcher-component-versions"></a>

This component has the following versions:
+ 2.0.x

## Type
<a name="lambda-launcher-component-type"></a>

<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
<a name="lambda-launcher-component-os-support"></a>

This component can be installed on Linux core devices only.

## Requirements
<a name="lambda-launcher-component-requirements"></a>

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
<a name="lambda-launcher-component-dependencies"></a>

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
<a name="lambda-launcher-component-configuration"></a>

This component doesn't have any configuration parameters.

## Local log file
<a name="lambda-launcher-component-log-file"></a>

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
<a name="lambda-launcher-component-changelog"></a>

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
<a name="lambda-manager-component"></a>

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
<a name="lambda-manager-component-versions"></a>

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

## Operating system
<a name="lambda-manager-component-os-support"></a>

This component can be installed on Linux core devices only.

## Type
<a name="lambda-manager-component-type"></a>

<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
<a name="lambda-manager-component-requirements"></a>

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
<a name="lambda-manager-component-dependencies"></a>

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
<a name="lambda-manager-component-configuration"></a>

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
<a name="lambda-manager-component-log-file"></a>

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
<a name="lambda-manager-component-changelog"></a>

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


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.3.8  |  Updates the component version for the Greengrass nucleus version 2.17.0 release.  | 
|  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
<a name="lambda-runtimes-component"></a>

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
<a name="lambda-runtimes-component-versions"></a>

This component has the following versions:
+ 2.0.x

## Type
<a name="lambda-runtimes-component-type"></a>

<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
<a name="lambda-runtimes-component-os-support"></a>

This component can be installed on Linux core devices only.

## Requirements
<a name="lambda-runtimes-component-requirements"></a>

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
<a name="lambda-runtimes-component-dependencies"></a>

This component doesn't have any dependencies.

## Configuration
<a name="lambda-runtimes-component-configuration"></a>

This component doesn't have any configuration parameters.

## Local log file
<a name="lambda-runtimes-component-log-file"></a>

This component doesn't output logs.

## Changelog
<a name="lambda-runtimes-component-changelog"></a>

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
<a name="legacy-subscription-router-component"></a>

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
<a name="legacy-subscription-router-component-versions"></a>

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

## Type
<a name="legacy-subscription-router-component-type"></a>

<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
<a name="legacy-subscription-router-component-os-support"></a>

This component can be installed on Linux core devices only.

## Requirements
<a name="legacy-subscription-router-component-requirements"></a>

This component has the following requirements:
+ The legacy subscription router is supported to run in a VPC.

## Dependencies
<a name="legacy-subscription-router-component-dependencies"></a>

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
<a name="legacy-subscription-router-component-configuration"></a>

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
<a name="legacy-subscription-router-component-log-file"></a>

This component doesn't output logs.

## Changelog
<a name="legacy-subscription-router-component-changelog"></a>

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


|  Version  |  Changes  | 
| --- | --- | 
|  2.1.16  |  Updates the component version for the Greengrass nucleus version 2.17.0 release.  | 
|  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
<a name="local-debug-console-component"></a>

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
<a name="local-debug-console-component-versions"></a>

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

## Type
<a name="local-debug-console-component-type"></a>

<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
<a name="local-debug-console-component-os-support"></a>

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

## Requirements
<a name="local-debug-console-component-requirements"></a>

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
<a name="local-debug-console-component-dependencies"></a>

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
<a name="local-debug-console-component-configuration"></a>

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
<a name="local-debug-console-component-usage"></a>

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
<a name="local-debug-console-component-log-file"></a>

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
<a name="local-debug-console-component-changelog"></a>

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


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.4.7  |  Updates the component version for the Greengrass nucleus version 2.17.0 release.  | 
|  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
<a name="log-manager-component"></a>

**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
<a name="log-manager-component-versions"></a>

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

## Type
<a name="log-manager-component-type"></a>

<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
<a name="log-manager-component-os-support"></a>

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

## Requirements
<a name="log-manager-component-requirements"></a>

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
<a name="log-manager-component-endpoints"></a>

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
<a name="log-manager-component-dependencies"></a>

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
<a name="log-manager-component-configuration"></a>

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
<a name="log-manager-component-usage"></a>

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.
<a name="log-manager-entry-format"></a>

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
<a name="log-manager-component-log-file"></a>

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
<a name="log-manager-component-changelog"></a>

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


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.3.12  |  Updates the component version for the Greengrass nucleus version 2.17.0 release.  | 
|  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
<a name="machine-learning-components"></a>

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
<a name="sagemaker-edge-manager-component"></a>

**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
<a name="sagemaker-edge-manager-component-versions"></a>

This component has the following versions:
+ 1.3.x
+ 1.2.x
+ 1.1.x
+ 1.0.x

## Type
<a name="sagemaker-edge-manager-component-type"></a>

<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
<a name="sagemaker-edge-manager-component-os-support"></a>

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

## Requirements
<a name="sagemaker-edge-manager-component-requirements"></a>

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
<a name="sagemaker-edge-manager-component-endpoints"></a>

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
<a name="sagemaker-edge-manager-component-dependencies"></a>

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
<a name="sagemaker-edge-manager-component-configuration"></a>

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
<a name="sagemaker-edge-manager-component-log-file"></a>

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
<a name="sagemaker-edge-manager-component-changelog"></a>

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
<a name="dlr-image-classification-component"></a>

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
<a name="dlr-image-classification-component-versions"></a>

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

## Type
<a name="dlr-image-classification-component-type"></a>

<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
<a name="dlr-image-classification-component-os-support"></a>

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

## Requirements
<a name="dlr-image-classification-component-requirements"></a>

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
<a name="dlr-image-classification-component-dependencies"></a>

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
<a name="dlr-image-classification-component-configuration"></a>

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
<a name="dlr-image-classification-component-log-file"></a>

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
<a name="dlr-image-classification-component-changelog"></a>

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
<a name="dlr-object-detection-component"></a>

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
<a name="dlr-object-detection-component-versions"></a>

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

## Type
<a name="dlr-object-detection-component-type"></a>

<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
<a name="dlr-object-detection-component-os-support"></a>

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

## Requirements
<a name="dlr-object-detection-component-requirements"></a>

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
<a name="dlr-object-detection-component-dependencies"></a>

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
<a name="dlr-object-detection-component-configuration"></a>

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
<a name="dlr-object-detection-component-log-file"></a>

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
<a name="dlr-object-detection-component-changelog"></a>

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
<a name="dlr-image-classification-model-store-component"></a>

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
<a name="dlr-image-classification-model-store-component-versions"></a>

This component has the following versions:
+ 2.1.x (`variant.DLR.ImageClassification.ModelStore`) 
+ 2.0.x (`variant.ImageClassification.ModelStore`) 

## Type
<a name="dlr-image-classification-model-store-component-type"></a>

<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
<a name="dlr-image-classification-model-store-component-os-support"></a>

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

## Requirements
<a name="dlr-image-classification-model-store-component-requirements"></a>

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
<a name="dlr-image-classification-model-store-component-dependencies"></a>

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
<a name="dlr-image-classification-model-store-component-configuration"></a>

This component doesn't have any configuration parameters.

## Local log file
<a name="dlr-image-classification-model-store-component-log-file"></a>

This component doesn't output logs.

## Changelog
<a name="dlr-image-classification-model-store-component-changelog"></a>

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
<a name="dlr-object-detection-model-store-component"></a>

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
<a name="dlr-object-detection-model-store-component-versions"></a>

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

## Type
<a name="dlr-object-detection-model-store-component-type"></a>

<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
<a name="dlr-object-detection-model-store-component-os-support"></a>

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

## Requirements
<a name="dlr-object-detection-model-store-component-requirements"></a>

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
<a name="dlr-object-detection-model-store-component-dependencies"></a>

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
<a name="dlr-object-detection-model-store-component-configuration"></a>

This component doesn't have any configuration parameters.

## Local log file
<a name="dlr-object-detection-model-store-component-log-file"></a>

This component doesn't output logs.

## Changelog
<a name="dlr-object-detection-model-store-component-changelog"></a>

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
<a name="dlr-component"></a>

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
<a name="dlr-component-versions"></a>

This component has the following versions:
+ 1.6.x
+ 1.3.x

## Type
<a name="dlr-component-type"></a>

<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
<a name="dlr-component-os-support"></a>

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

## Requirements
<a name="dlr-component-requirements"></a>

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
<a name="dlr-component-endpoints"></a>

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
<a name="dlr-component-dependencies"></a>

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
<a name="dlr-component-configuration"></a>

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
<a name="dlr-component-usage"></a>

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
<a name="dlr-component-log-file"></a>

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
<a name="dlr-component-changelog"></a>

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
<a name="tensorflow-lite-image-classification-component"></a>

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
<a name="tensorflow-lite-image-classification-component-versions"></a>

This component has the following versions:
+ 2.1.x

## Type
<a name="tensorflow-lite-image-classification-component-type"></a>

<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
<a name="tensorflow-lite-image-classification-component-os-support"></a>

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

## Requirements
<a name="tensorflow-lite-image-classification-component-requirements"></a>

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
<a name="tensorflow-lite-image-classification-component-dependencies"></a>

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
<a name="tensorflow-lite-image-classification-component-configuration"></a>

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
<a name="tensorflow-lite-image-classification-component-log-file"></a>

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
<a name="tensorflow-lite-image-classification-component-changelog"></a>

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
<a name="tensorflow-lite-object-detection-component"></a>

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
<a name="tensorflow-lite-object-detection-component-versions"></a>

This component has the following versions:
+ 2.1.x

## Type
<a name="tensorflow-lite-object-detection-component-type"></a>

<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
<a name="tensorflow-lite-object-detection-component-os-support"></a>

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

## Requirements
<a name="tensorflow-lite-object-detection-component-requirements"></a>

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
<a name="tensorflow-lite-object-detection-component-dependencies"></a>

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
<a name="tensorflow-lite-object-detection-component-configuration"></a>

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
<a name="tensorflow-lite-object-detection-component-log-file"></a>

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
<a name="tensorflow-lite-object-detection-component-changelog"></a>

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
<a name="tensorflow-lite-image-classification-model-store-component"></a>

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
<a name="tensorflow-lite-image-classification-model-store-component-versions"></a>

This component has the following versions:
+ 2.1.x

## Type
<a name="tensorflow-lite-image-classification-model-store-component-type"></a>

<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
<a name="tensorflow-lite-image-classification-model-store-component-os-support"></a>

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

## Requirements
<a name="tensorflow-lite-image-classification-model-store-component-requirements"></a>

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
<a name="tensorflow-lite-image-classification-model-store-component-dependencies"></a>

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
<a name="tensorflow-lite-image-classification-model-store-component-configuration"></a>

This component doesn't have any configuration parameters.

## Local log file
<a name="tensorflow-lite-image-classification-model-store-component-log-file"></a>

This component doesn't output logs.

## Changelog
<a name="tensorflow-lite-image-classification-model-store-component-changelog"></a>

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
<a name="tensorflow-lite-object-detection-model-store-component"></a>

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
<a name="tensorflow-lite-object-detection-model-store-component-versions"></a>

This component has the following versions:
+ 2.1.x

## Type
<a name="tensorflow-lite-object-detection-model-store-component-type"></a>

<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
<a name="tensorflow-lite-object-detection-model-store-component-os-support"></a>

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

## Requirements
<a name="tensorflow-lite-object-detection-model-store-component-requirements"></a>

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
<a name="tensorflow-lite-object-detection-model-store-component-dependencies"></a>

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
<a name="tensorflow-lite-object-detection-model-store-component-configuration"></a>

This component doesn't have any configuration parameters.

## Local log file
<a name="tensorflow-lite-object-detection-model-store-component-log-file"></a>

This component doesn't output logs.

## Changelog
<a name="tensorflow-lite-object-detection-model-store-component-changelog"></a>

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
<a name="tensorflow-lite-component"></a>

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
<a name="tensorflow-lite-component-versions"></a>

This component has the following versions:
+ 2.5.x

## Type
<a name="tensorflow-lite-component-type"></a>

<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
<a name="tensorflow-lite-component-os-support"></a>

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

## Requirements
<a name="tensorflow-lite-component-requirements"></a>

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
<a name="tensorflow-lite-component-endpoints"></a>

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
<a name="tensorflow-lite-component-dependencies"></a>

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
<a name="tensorflow-lite-component-configuration"></a>

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
<a name="tensorflow-lite-component-usage"></a>

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
<a name="tensorflow-lite-component-log-file"></a>

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
<a name="tensorflow-lite-component-changelog"></a>

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
<a name="modbus-rtu-protocol-adapter-component"></a>

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
<a name="modbus-rtu-protocol-adapter-component-versions"></a>

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

## Type
<a name="modbus-rtu-protocol-adapter-component-type"></a>

<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
<a name="modbus-rtu-protocol-adapter-component-os-support"></a>

This component can be installed on Linux core devices only.

## Requirements
<a name="modbus-rtu-protocol-adapter-component-requirements"></a>

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
<a name="modbus-rtu-protocol-adapter-component-dependencies"></a>

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
<a name="modbus-rtu-protocol-adapter-component-configuration"></a>

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
<a name="modbus-rtu-protocol-adapter-component-input-data"></a>

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="modbus-rtu-protocol-adapter-component-output-data"></a>

 <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
<a name="modbus-rtu-protocol-adapter-component-requests-responses"></a>

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
<a name="modbus-rtu-protocol-adapter-component-examples"></a>

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
<a name="modbus-rtu-protocol-adapter-component-response-exception"></a>

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
<a name="modbus-rtu-protocol-adapter-component-response-noresponse"></a>

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
<a name="modbus-rtu-protocol-adapter-component-log-file"></a>

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
<a name="modbus-rtu-protocol-adapter-component-licenses"></a>

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
<a name="modbus-rtu-protocol-adapter-component-changelog"></a>

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
<a name="mqtt-bridge-component"></a>

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
<a name="mqtt-bridge-component-versions"></a>

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

## Type
<a name="mqtt-bridge-component-type"></a>

<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
<a name="mqtt-bridge-component-os-support"></a>

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

## Requirements
<a name="mqtt-bridge-component-requirements"></a>

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
<a name="mqtt-bridge-component-dependencies"></a>

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
<a name="mqtt-bridge-component-configuration"></a>

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
<a name="mqtt-bridge-component-log-file"></a>

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
<a name="mqtt-bridge-component-changelog"></a>

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)
<a name="mqtt-broker-moquette-component"></a>

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
<a name="mqtt-broker-moquette-component-versions"></a>

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

## Type
<a name="mqtt-broker-moquette-component-type"></a>

<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
<a name="mqtt-broker-moquette-component-os-support"></a>

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

## Requirements
<a name="mqtt-broker-moquette-component-requirements"></a>

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
<a name="mqtt-broker-moquette-component-dependencies"></a>

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
<a name="mqtt-broker-moquette-component-configuration"></a>

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
<a name="mqtt-broker-moquette-component-log-file"></a>

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
<a name="mqtt-broker-moquette-component-changelog"></a>

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)
<a name="mqtt-broker-emqx-component"></a>

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
<a name="mqtt-broker-emqx-component-versions"></a>

This component has the following versions:
+ 2.0.x
+ 1.2.x
+ 1.1.x
+ 1.0.x

## Type
<a name="mqtt-broker-emqx-component-type"></a>

<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
<a name="mqtt-broker-emqx-component-os-support"></a>

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

## Requirements
<a name="mqtt-broker-emqx-component-requirements"></a>

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
<a name="mqtt-broker-emqx-component-dependencies"></a>

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
<a name="mqtt-broker-emqx-component-configuration"></a>

------
#### [ 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
<a name="mqtt-broker-emqx-component-log-file"></a>

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
<a name="mqtt-broker-emqx-component-licenses"></a>

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
<a name="mqtt-broker-emqx-component-changelog"></a>

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
<a name="nucleus-emitter-component"></a>

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
<a name="nucleus-emitter-component-versions"></a>

This component has the following versions:
+ 1.0.x

## Type
<a name="nucleus-emitter-component-type"></a>

<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
<a name="nucleus-emitter-component-os-support"></a>

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

## Dependencies
<a name="nucleus-emitter-component-dependencies"></a>

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
<a name="nucleus-emitter-component-configuration"></a>

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
<a name="nucleus-emitter-component-output-data"></a>

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
<a name="nucleus-emitter-component-usage"></a>

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
<a name="nucleus-emitter-component-log-file"></a>

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
<a name="nucleus-emitter-component-changelog"></a>

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


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  1.0.13  |  Updates the component version for the Greengrass nucleus version 2.17.0 release.  | 
|  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
<a name="pkcs11-provider-component"></a>

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

**Note**  
This component is required for [Greengrass nucleus](greengrass-nucleus-component.md) only. [Greengrass nucleus lite](greengrass-nucleus-lite-component.md) v2.5.0 and later includes built-in PKCS\$111 support and does not require this component. For more information, see [PKCS\$111 support](https://github.com/aws-greengrass/aws-greengrass-lite/blob/main/docs/PKCS11_SUPPORT.md) in the AWS IoT Greengrass nucleus lite GitHub repository.

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
<a name="pkcs11-provider-component-versions"></a>

This component has the following versions:
+ 2.0.x

## Type
<a name="pkcs11-provider-component-type"></a>

<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
<a name="pkcs11-provider-component-os-support"></a>

This component can be installed on Linux core devices only.

## Requirements
<a name="pkcs11-provider-component-requirements"></a>

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
<a name="pkcs11-provider-component-dependencies"></a>

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
<a name="pkcs11-provider-component-configuration"></a>

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
<a name="pkcs11-provider-component-log-file"></a>

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
<a name="pkcs11-provider-component-changelog"></a>

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


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.0.12  |  Updates the component version for the Greengrass nucleus version 2.17.0 release.  | 
|  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
<a name="secret-manager-component"></a>

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
<a name="secret-manager-component-versions"></a>

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

## Type
<a name="secret-manager-component-type"></a>

<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
<a name="secret-manager-component-os-support"></a>

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

## Requirements
<a name="secret-manager-component-requirements"></a>

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
<a name="secret-manager-component-endpoints"></a>

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
<a name="secret-manager-component-dependencies"></a>

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
<a name="secret-manager-component-configuration"></a>

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
<a name="secret-manager-component-log-file"></a>

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
<a name="secret-manager-component-changelog"></a>

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


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.2.8  |  Updates the component version for the Greengrass nucleus version 2.17.0 release.  | 
|  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
<a name="secure-tunneling-component"></a>

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
<a name="secure-tunneling-component-versions"></a>

This component has the following versions:
+ 2.0.x
+ 1.1.x
+ 1.0.x

## Type
<a name="secure-tunneling-component-type"></a>

<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
<a name="secure-tunneling-component-os-support"></a>

This component can be installed on Linux core devices only.

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

## Requirements
<a name="secure-tunneling-component-requirements"></a>

This component has the following requirements:

------
#### [ 2.0.x ]
+ Minimum of 4 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 3 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.
+ GNU C Library (glibc) version 2.35 or 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.
+ The following runtime libraries installed on the Greengrass core device:
  + `libstdc++` version 3.4.29 or greater
  + `libgcc_s` version 3.0 or greater
  + OpenSSL version 3.0.0 or greater
+ 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.

------
#### [ 1.0.x - 1.1.x ]
+ 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
<a name="secure-tunneling-component-endpoints"></a>

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
<a name="secure-tunneling-component-dependencies"></a>

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.

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

Version 2.0.0 of this component supports both Greengrass nucleus and Greengrass nucleus lite. 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) OR [Greengrass nucleus lite](greengrass-nucleus-lite-component.md) |  >=2.0.0 <3.0.0  | Soft | 

------
#### [ 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
<a name="secure-tunneling-component-configuration"></a>

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

------
#### [ 2.0.x ]

`maxConcurrentTunnels`  
(Optional) Maximum number of concurrent tunnels allowed.  
The value cannot be more than 20.
Default: `20`

`tunnelTimeoutSeconds`  
(Optional) Tunnel timeout duration in seconds.  
Default: `43200` (12 hours)

`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.greengrass.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 the maximum concurrent tunnels and timeout settings.  

```
{
  "maxConcurrentTunnels": 20,
  "tunnelTimeoutSeconds": 43200,
  "accessControl": {
    "aws.greengrass.ipc.mqttproxy": {
      "aws.greengrass.SecureTunneling:mqttproxy:1": {
        "policyDescription": "Access to tunnel notification pubsub topic",
        "operations": [
          "aws.greengrass#SubscribeToIoTCore"
        ],
        "resources": [
          "$aws/things/MyGreengrassCore/tunnels/notify"
        ]
      }
    }
  }
}
```

------
#### [ 1.0.x - 1.1.x ]

`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
<a name="secure-tunneling-component-log-file"></a>

------
#### [ Greengrass nucleus ]

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
  ```

------
#### [ Greengrass nucleus lite ]

Run the following command on the core device to view this component's logs.

```
journalctl -xeau ggl.aws.greengrass.SecureTunneling.service
```

Run the following command on the core device to view this component's logs in real time.

```
journalctl -fau ggl.aws.greengrass.SecureTunneling.service
```

------

## Licenses
<a name="secure-tunneling-component-licenses"></a>

This component includes the following third-party software/licensing:

------
#### [ 2.0.x ]
+ [AWS IoT Secure Tunneling Local Proxy](https://github.com/aws-samples/aws-iot-securetunneling-localproxy)/Apache License 2.0
+ [AWS Greengrass Component SDK](https://github.com/aws-greengrass/aws-greengrass-component-sdk)/Apache License 2.0
+ [Boost C\$1\$1 Libraries](https://www.boost.org/)/Boost Software License 1.0
+ [Protocol Buffers](https://github.com/protocolbuffers/protobuf)/BSD 3-Clause License

------
#### [ 1.0.x - 1.1.x ]
+ [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
<a name="secure-tunneling-component-usage"></a>

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
<a name="secure-tunneling-component-see-also"></a>
+ [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
<a name="secure-tunneling-component-changelog"></a>

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


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.0.0  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/secure-tunneling-component.html)  | 
|  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
<a name="shadow-manager-component"></a>

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
<a name="shadow-manager-component-versions"></a>

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

## Type
<a name="shadow-manager-component-type"></a>

<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
<a name="shadow-manager-component-os-support"></a>

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

## Requirements
<a name="shadow-manager-component-requirements"></a>

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
<a name="shadow-manager-component-dependencies"></a>

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
<a name="shadow-manager-component-configuration"></a>

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
<a name="shadow-manager-component-log-file"></a>

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
<a name="shadow-manager-component-changelog"></a>

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


|  Version  |  Changes  | 
| --- | --- | 
|  2.3.13  |  Updates the component version for the Greengrass nucleus version 2.17.0 release.  | 
|  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
<a name="sns-component"></a>

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
<a name="sns-component-versions"></a>

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

## Type
<a name="sns-component-type"></a>

<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
<a name="sns-component-os-support"></a>

This component can be installed on Linux core devices only.

## Requirements
<a name="sns-component-requirements"></a>

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
<a name="sns-component-endpoints"></a>

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
<a name="sns-component-dependencies"></a>

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
<a name="sns-component-configuration"></a>

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
<a name="sns-component-input-data"></a>

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="sns-component-output-data"></a>

 <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
<a name="sns-component-log-file"></a>

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
<a name="sns-component-licenses"></a>

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
<a name="sns-component-changelog"></a>

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
<a name="stream-manager-component"></a>

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
<a name="stream-manager-component-versions"></a>

This component has the following versions:
+ 2.3.x
+ 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="stream-manager-component-type"></a>

<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
<a name="stream-manager-component-os-support"></a>

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

## Requirements
<a name="stream-manager-component-requirements"></a>

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
<a name="stream-manager-component-endpoints"></a>

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
<a name="stream-manager-component-dependencies"></a>

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.3.0 ]

The following table lists the dependencies for versions 2.1.3 to 2.3.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.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
<a name="stream-manager-component-configuration"></a>

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
<a name="stream-manager-component-log-file"></a>

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
<a name="stream-manager-component-changelog"></a>

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


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.3.0  | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/stream-manager-component.html) | 
|  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
<a name="system-log-forwarder-component"></a>

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
<a name="system-log-forwarder-component-versions"></a>

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

## Type
<a name="system-log-forwarder-component-type"></a>

<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
<a name="system-log-forwarder-component-os-support"></a>

This component must be installed on systemd-based Linux systems.

## Requirements
<a name="system-log-forwarder-component-requirements"></a>

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
<a name="system-log-forwarder-component-endpoints"></a>

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
<a name="system-log-forwarder-component-dependencies"></a>

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
<a name="system-log-forwarder-component-configuration"></a>

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
<a name="system-log-forwarder-component-changelog"></a>

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
<a name="systems-manager-agent-component"></a>

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
<a name="systems-manager-agent-component-versions"></a>

This component has the following versions:
+ 1.3.x
+ 1.2.x
+ 1.1.x
+ 1.0.x

## Type
<a name="systems-manager-agent-component-type"></a>

<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
<a name="systems-manager-agent-component-os-support"></a>

This component can be installed on Linux core devices only.

## Requirements
<a name="systems-manager-agent-component-requirements"></a>

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
<a name="systems-manager-agent-component-endpoints"></a>

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
<a name="systems-manager-agent-component-dependencies"></a>

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
<a name="systems-manager-agent-component-configuration"></a>

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
<a name="systems-manager-agent-component-log-file"></a>

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
<a name="systems-manager-agent-component-see-also"></a>
+ [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
<a name="systems-manager-agent-component-changelog"></a>

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
<a name="token-exchange-service-component"></a>

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
<a name="token-exchange-service-component-versions"></a>

This component has the following versions:
+ 2.0.x

## Type
<a name="token-exchange-service-component-type"></a>

<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
<a name="token-exchange-service-component-os-support"></a>

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

## Dependencies
<a name="token-exchange-service-component-dependencies"></a>

This component doesn't have any dependencies.

## Configuration
<a name="token-exchange-service-component-configuration"></a>

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
<a name="token-exchange-service-component-log-file"></a>

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
<a name="token-exchange-service-component-changelog"></a>

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


|  **Version**  |  **Changes**  | 
| --- | --- | 
|  2.0.3  |  Initial version.  | 

# IoT SiteWise OPC UA collector
<a name="iotsitewise-opcua-collector-component"></a>

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
<a name="iotsitewise-opcua-collector-component-versions"></a>

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="iotsitewise-opcua-collector-component-type"></a>

<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
<a name="iotsitewise-opcua-collector-component-os-support"></a>

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

## Requirements
<a name="iotsitewise-opcua-collector-component-requirements"></a>

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
<a name="iotsitewise-opcua-collector-component-dependencies"></a>

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
<a name="iotsitewise-opcua-collector-component-configuration"></a>

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
<a name="iotsitewise-opcua-collector-component-input-data"></a>

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
<a name="iotsitewise-opcua-collector-component-output-data"></a>



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
<a name="iotsitewise-opcua-collector-component-log-file"></a>

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="iotsitewise-opcua-collector-component-licenses"></a>

<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
<a name="iotsitewise-opcua-collector-component-changelog"></a>

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
<a name="iotsitewise-opcua-collector-component-see-also"></a>
+ [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
<a name="iotsitewise-opcua-data-source-simulator-component"></a>

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
<a name="iotsitewise-opcua-data-source-simulator-component-versions"></a>

This component has the following versions:
+ 1.0.x

## Type
<a name="iotsitewise-opcua-data-source-simulator-component-type"></a>

<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
<a name="iotsitewise-opcua-data-source-simulator-component-os-support"></a>

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

## Requirements
<a name="iotsitewise-opcua-data-source-simulator-component-requirements"></a>

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
<a name="iotsitewise-opcua-data-source-simulator-component-dependencies"></a>

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
<a name="iotsitewise-opcua-data-source-simulator-component-configuration"></a>

This component doesn't have any configuration parameters.

## Local log file
<a name="iotsitewise-opcua-data-source-simulator-component-log-file"></a>

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
<a name="iotsitewise-opcua-data-source-simulator-component-changelog"></a>

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
<a name="iotsitewise-opcua-data-source-simulator-component-see-also"></a>
+ [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
<a name="iotsitewise-publisher-component"></a>

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
<a name="iotsitewise-publisher-component-versions"></a>

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="iotsitewise-publisher-component-type"></a>

<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
<a name="iotsitewise-publisher-component-os-support"></a>

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

## Requirements
<a name="iotsitewise-publisher-component-requirements"></a>

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
<a name="iotsitewise-publisher-component-endpoints"></a>

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
<a name="iotsitewise-publisher-component-dependencies"></a>

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
<a name="iotsitewise-publisher-component-configuration"></a>

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
<a name="iotsitewise-publisher-component-input-data"></a>



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
<a name="iotsitewise-publisher-component-log-file"></a>

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
<a name="iotsitewise-publisher-component-debug"></a>

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="iotsitewise-publisher-component-licenses"></a>

<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
<a name="iotsitewise-publisher-component-changelog"></a>

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
<a name="iotsitewise-publisher-component-see-also"></a>
+ [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
<a name="iotsitewise-processor-component"></a>

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
<a name="iotsitewise-processor-component-versions"></a>

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="iotsitewise-processor-component-type"></a>

<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
<a name="iotsitewise-processor-component-os-support"></a>

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

## Requirements
<a name="iotsitewise-processor-component-requirements"></a>

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
<a name="iotsitewise-processor-component-endpoints"></a>

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
<a name="iotsitewise-processor-component-dependencies"></a>

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
<a name="iotsitewise-processor-component-configuration"></a>

This component doesn't have any configuration parameters.

## Local log file
<a name="iotsitewise-processor-component-log-file"></a>

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
<a name="iotsitewise-processor-component-licenses"></a>

This component includes the following third-party software/licensing:

### Third-party Licenses
<a name="w2ab1c24b8d120c25b5b1b1"></a>
+ 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
<a name="iotsitewise-processor-component-changelog"></a>

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
<a name="iotsitewise-processor-component-see-also"></a>
+ [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*.