Versions Type Operating system Requirements Dependencies Configuration Local log file See also Changelog

Systems Manager Agent

The AWS Systems Manager Agent component (aws.greengrass.SystemsManagerAgent) installs the Systems Manager Agent, so you can manage core devices with Systems Manager. Systems Manager is an AWS service that you can use to view and control your infrastructure on AWS, including Amazon EC2 instances, on-premises servers and virtual machines (VMs), and edge devices. Systems Manager enables you to view operational data, automate operation tasks, and maintain security and compliance. For more information, see What is AWS Systems Manager? and About Systems Manager Agent in the AWS 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 AWS Systems Manager User Guide.

Versions

This component has the following versions:

1.1.x
1.0.x

Type

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.

Requirements

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 AWS 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 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 must allow the ssm:AddTagsToResource and ssm:RegisterManagedInstance actions. The device role must also allow the iam:PassRole action for the IAM service role that fulfills the previous requirement. The following example IAM policy grants these permissions.


{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": [
        "iam:PassRole"
      ],
      "Effect": "Allow",
      "Resource": [
        "arn:aws:iam::account-id:role/SSMServiceRole"
      ]
    },
    {
      "Action": [
        "ssm:AddTagsToResource",
        "ssm:RegisterManagedInstance"
      ],
      "Effect": "Allow",
      "Resource": "*"
    }
  ]
}

Endpoints and ports

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

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

Dependencies

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

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.

Configuration

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

SSMRegistrationRole

The IAM service role that Systems Manager can assume and that includes the AmazonSSMManagedInstanceCore managed policy or a custom policy that defines equivalent permissions. For more information, see Create an IAM service role for edge devices 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.

Note

This option applies only to devices that are registered with a hybrid activation. If the core device runs on an Amazon EC2 instance with the Systems Manager Agent installed and an instance profile role configured, the Amazon EC2 instance's existing managed node ID starts with i-. When you install the Systems Manager Agent component, the Systems Manager agent registers a new managed node whose ID starts with mi- instead of i-. Then, you can use the managed node whose ID starts with mi- to manage the core device with Systems Manager.

Default: false

SSMResourceTags

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

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


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

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

Example: Configuration merge update

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


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

Local log file

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

Changelog

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

Version	Changes
1.2.4	Bug fixes and improvments Updates this component to get the Agent version 3.2.2303.0.
1.2.3	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.
1.1.0	This version contains bug fixes and improvements.
1.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

Stream manager

Token exchange service