Versions Type Operating system Requirements Dependencies Configuration Local log file Changelog

Shadow manager

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

Versions

This component has the following versions:

2.3.x
2.2.x
2.1.x
2.0.x

Type

This component is a plugin component (aws.greengrass.plugin). The Greengrass nucleus 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.

This component uses the same log file as the Greengrass nucleus. For more information, see Monitor AWS IoT Greengrass logs.

For more information, see Component types.

Operating system

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

Linux
Windows

Requirements

This component has the following requirements:

(Optional) To sync shadows to the AWS IoT Device Shadow service, the Greengrass core device's AWS IoT policy must allow the following AWS IoT Core shadow policy actions:
- iot:GetThingShadow
- iot:UpdateThingShadow
- iot:DeleteThingShadow
For more information about these AWS IoT Core policies, see AWS IoT Core policy actions 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
The shadow manager component is supported to run in a VPC.

Dependencies

When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the released versions 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. On the component details page, look for the Dependencies list.

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	>=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	>=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	>=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	>=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	>=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	>=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	>=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	>=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	>=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	>=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	>=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	>=2.2.0 <2.3.0	Soft

For more information about component dependencies, see the component recipe reference.

Configuration

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

2.3.x

strategy

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

Note

This parameter is required if you specify the periodic sync strategy.

synchronize

(Optional) The synchronization settings that determine how shadows are synced with the AWS Cloud.

Note

You must create a configuration update with this property to sync shadows with the AWS Cloud.

This object contains the following information.

coreThing

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

Warning

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

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

Note

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

(Optional) The list of additional device shadows to sync. We recommend that you use the shadowDocumentsMap parameter instead.

Note

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

(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

Note

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 in the Amazon Web Services General Reference.

shadowDocumentSizeLimitBytes

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

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

Note

This parameter is required if you specify the periodic sync strategy.

synchronize

(Optional) The synchronization settings that determine how shadows are synced with the AWS Cloud.

Note

You must create a configuration update with this property to sync shadows with the AWS Cloud.

This object contains the following information.

coreThing

(Optional) The core device shadows to sync. This object contains the following information.

classic

Default: true

namedShadows

(Optional) The list of named core device shadows to sync. You must specify the exact names of the shadows.

Warning

shadowDocumentsMap

Note

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

(Optional) The list of additional device shadows to sync. We recommend that you use the shadowDocumentsMap parameter instead.

Note

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

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

(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

Note

shadowDocumentSizeLimitBytes

(Optional) The maximum allowed size of each JSON state document for local shadows.

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

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

Note

This parameter is required if you specify the periodic sync strategy.

synchronize

(Optional) The synchronization settings that determine how shadows are synced with the AWS Cloud.

Note

You must create a configuration update with this property to sync shadows with the AWS Cloud.

This object contains the following information.

coreThing

(Optional) The core device shadows to sync. This object contains the following information.

classic

Default: true

namedShadows

(Optional) The list of named core device shadows to sync. You must specify the exact names of the shadows.

Warning

shadowDocumentsMap

Note

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

(Optional) The list of additional device shadows to sync. We recommend that you use the shadowDocumentsMap parameter instead.

Note

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

(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

Note

shadowDocumentSizeLimitBytes

(Optional) The maximum allowed size of each JSON state document for local shadows.

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

(Optional) The synchronization settings that determine how shadows are synced with the AWS Cloud.

Note

You must create a configuration update with this property to sync shadows with the AWS Cloud.

This object contains the following information.

coreThing

(Optional) The core device shadows to sync. This object contains the following information.

classic

Default: true

namedShadows

(Optional) The list of named core device shadows to sync. You must specify the exact names of the shadows.

Warning

shadowDocumentsMap

Note

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

(Optional) The list of additional device shadows to sync. We recommend that you use the shadowDocumentsMap parameter instead.

Note

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

(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

Note

shadowDocumentSizeLimitBytes

(Optional) The maximum allowed size of each JSON state document for local shadows.

Default: 8192 bytes

Maximum: 30720 bytes

Example: Configuration merge update

The following example shows a sample configuration merge update with all available configuration parameters for the shadow manager component.


{
  "synchronize": {
    "coreThing": {
      "classic": true,
      "namedShadows": [
        "MyCoreShadowA",
        "MyCoreShadowB"
      ]
    },
    "shadowDocuments": [
      {
        "thingName": "MyDevice1",
        "classic": false,
        "namedShadows": [
          "MyShadowA",
          "MyShadowB"
        ]
      },
      {
        "thingName": "MyDevice2",
        "classic": true,
        "namedShadows": []
      }
    ]
  },
  "rateLimits": {       
    "maxOutboundSyncUpdatesPerSecond": 100,
    "maxTotalLocalRequestsRate": 200,
    "maxLocalRequestsPerSecondPerThing": 20
  },
  "shadowDocumentSizeLimitBytes": 8192
}

Local log file

This component uses the same log file as the Greengrass nucleus component.

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:\greengrass\v2 with the path to the AWS IoT Greengrass root folder.
Linux
```
sudo tail -f /greengrass/v2/logs/greengrass.log
```
Windows (PowerShell)
```
Get-Content C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait
```

Changelog

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

Version	Changes
2.3.8	Bug fixes and improvements Fixes an issue where shadow manager creates a deadlock situation during the MQTT client connection.
2.3.7	Bug fixes and improvements Fixes an issue where shadow manager periodically logs a `NullPointerException` error during a shadow manager sync.
2.3.6	Bug fixes and improvements Fixes an issue where shadow properties that are deleted through AWS Cloud updates while the device is offline continue to exist in the local shadow after regaining connectivity.
2.3.5	Version updated for Greengrass nucleus version 2.12.0 release.
2.3.4	Bug fixes and improvements Adds support for null and empty shadow state documents.
2.3.3	Version updated for Greengrass nucleus version 2.11.0 release.
2.3.2	Bug fixes and improvements Fixes an issue where shadow manager enters the `BROKEN` state when the local shadow database is corrupted. Version updated for Greengrass nucleus version 2.10.0 release.
2.3.1	Bug fixes and improvements Fixes a condition that may prevent cloud shadow updates from syncing. Fixes an issue where changes to named shadow sync configuration applies to only one named shadow.
2.3.0	Bug fixes and improvements Fixes an issue that might prevent shadows from syncing when the Greengrass device private key is stored in a hardware security module.
2.2.4	Bug fixes and improvements Fixes an issue where the validation of the shadow's size wasn't consistent with the cloud when updating the local shadow document. Fixes an issue where the shadow manager stops listening to configuration updates if a deployment performs a `RESET` on the configuration nodes.
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	New features Adds support for the local shadow service over the local publish/subscribe interface. You can now communicate with the local publish/subscribe message broker on shadow MQTT topics to get, update, and delete shadows on the core device. This feature enables you to connect client devices to the local shadow service by using the MQTT bridge to relay messages on shadow topics between client devices and the local publish/subscribe interface. This feature requires v2.6.0 or later of the Greengrass nucleus component. To connect client devices to the local shadow service, you must also use v2.2.0 or later of the MQTT bridge component. Adds the `direction` option that you can configure to customize 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.
2.1.1	Bug fixes and improvements Fixes an issue where the maximum depth in the `desired` and `reported` sections of the JSON device shadow state document was 4 levels instead of 5 levels. Version updated for Greengrass nucleus version 2.6.0 release.
2.1.0	New features Adds support for periodic shadow synchronization intervals, so you can configure the core device to reduce bandwidth usage and charges.
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	Bug fixes and improvements Fixes an issue that caused shadow manager to delete newly created versions of any shadow that was previously deleted. Updates the `DeleteThingShadow` IPC operation to increment the shadow version when called.
2.0.3	Version updated for Greengrass nucleus version 2.4.0 release.
2.0.2	Bug fixes and improvements Fixed an issue that caused shadow manager to not recognize the `delta` property when syncing shadow states from AWS IoT Core. Fixed an issue that sometimes caused sync requests for a shadow to be merged incorrectly.
2.0.1	Version updated for Greengrass nucleus version 2.3.0 release.
2.0.0	Initial version.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Secure tunneling

Amazon SNS