Systems Manager Agent - Amazon IoT Greengrass
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Systems Manager Agent

The Amazon 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 Amazon service that you can use to view and control your infrastructure on Amazon, 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 Amazon Systems Manager? and About Systems Manager Agent in the Amazon Systems Manager User Guide.

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 in the Amazon Systems Manager User Guide.


This component has the following versions:

  • 1.1.x

  • 1.0.x


This component is a generic component (aws.greengrass.generic). The Greengrass nucleus runs the component's lifecycle scripts.

For more information, see Component types.

Operating system

This component can be installed on Linux core devices only.


This component has the following requirements:

  • A Greengrass core device that runs on a 64-bit Linux platform: Armv8 (AArch64) or x86_64.

  • You must have an Amazon Identity and Access Management (IAM) service role that Systems Manager can assume. This role must include the AmazonSSMManagedInstanceCore managed policy or a custom policy that defines equivalent permissions. For more information, see Create an IAM service role for edge devices in the Amazon 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 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-cn:iam::account-id:role/SSMServiceRole" ] }, { "Action": [ "ssm:AddTagsToResource", "ssm:RegisterManagedInstance" ], "Effect": "Allow", "Resource": "*" } ] }

Endpoints and ports

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

Endpoint Port Required Description

443 Yes

Communicate with the Systems Manager service in the Amazon Web Services Cloud.

443 Yes

Register the core device as a Systems Manager managed node.

443 Yes

Communicate with Session Manager, a capability of Systems Manager, in the Amazon Web Services Cloud.

For more information, see Reference: ec2messages, ssmmessages, and other API calls in the Amazon Systems Manager User Guide.


When you deploy a component, Amazon 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 Amazon IoT Greengrass console. On the component details page, look for the Dependencies list.

The following table lists the dependencies for versions 1.0.0 to 1.2.4 of this component.

Dependency Compatible versions Dependency type
Token exchange service ^2.0.0 Soft

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


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


The IAM service role that Systems Manager can assume and that includes the AmazonSSMManagedInstanceCore managed policy or a custom policy that defines equivalent permissions. For more information, see Create an IAM service role for edge devices in the Amazon Systems Manager User Guide.


(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


(Optional) The tags to add to the Systems Manager managed node that this component creates for the core device. You can use these tags to manage groups of core devices with Systems Manager. For example, you can run a command on all devices that have a tag that you specify.

Specify a list where each tag is an object with a Key and a Value. For example, the following value for SSMResourceTags instructs this component to set the Owner tag to richard-roe on the core device's managed node.

[ { "Key": "Owner", "Value": "richard-roe" } ]

This component ignores these tags if the managed node already exists and SSMOverrideExistingRegistration is false.

Example: Configuration merge update

The following example configuration specifies to use a service role named SSMServiceRole to allow the core device to register and communicate with Systems Manager.

{ "SSMRegistrationRole": "SSMServiceRole", "SSMOverrideExistingRegistration": false, "SSMResourceTags": [ { "Key": "Owner", "Value": "richard-roe" }, { "Key": "Team", "Value": "solar" } ] }

Local log file

The Systems Manager Agent software writes logs to a folder outside the Greengrass root folder. For more information, see Viewing Systems Manager Agent logs in the Amazon 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.

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 Amazon IoT Greengrass root folder.

    sudo tail -f /greengrass/v2/logs/aws.greengrass.SystemsManagerAgent.log

See also


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




Bug fixes and improvments

Updates this component to get the Agent version 3.2.2303.0.


Bug fixes and improvements
  • Adds retries for the Agent component's installation with snap on Greengrass.

  • Updates the Agent component's configuration to use only the Onprem Identity in Greengrass.

  • Updates this component to update the Agent only when the installed Agent version doesn't match the Greengrass SSM Agent component's version.


This version contains bug fixes and improvements.


Initial version.