Supported platforms and requirements Feature considerations for Windows devices Set up an Amazon Web Services account

Setting up Amazon IoT Greengrass core devices

Complete the tasks in this section to install, configure, and run the Amazon IoT Greengrass Core software.

Note

This section describes advanced installation and configuration of the Amazon IoT Greengrass Core software. If you're a first-time user of Amazon IoT Greengrass V2, we recommend that you first complete the getting started tutorial to set up a core device and explore the features of Amazon IoT Greengrass.

Supported platforms and requirements

Before you begin, make sure you meet the following requirements to install and run the Amazon IoT Greengrass Core software.

Tip

You can search for devices that are qualified for Amazon IoT Greengrass V2 in the Amazon Partner Device Catalog.

Supported platforms

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

Linux platforms can also run Amazon IoT Greengrass V2 in a Docker container. For more information, see Run Amazon IoT Greengrass Core software in a Docker container.

To build a custom Linux-based operating system, you can use the BitBake recipe for Amazon IoT Greengrass V2 in the meta-aws project. The meta-aws project provides recipes that you can use to build Amazon edge software capabilities in embedded Linux systems that are built with OpenEmbedded and Yocto Project build frameworks. The Yocto Project 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 Amazon IoT Greengrass V2 installs, configures, and automatically runs the Amazon IoT Greengrass Core software on your device.

Device requirements

Devices must meet the following requirements to install and run the Amazon IoT Greengrass Core software v2.x.

Note

You can use Amazon IoT Device Tester for Amazon IoT Greengrass to verify that your device can run the Amazon IoT Greengrass Core software and communicate with the Amazon Web Services Cloud. For more information, see Using Amazon IoT Device Tester for Amazon IoT Greengrass V2.

Linux

The use of an Amazon Web Services Region that supports Amazon IoT Greengrass V2. For the list of supported Regions, see Amazon IoT Greengrass V2 endpoints and quotas in the Amazon Web Services General Reference.
Minimum 256 MB disk space available for the Amazon IoT Greengrass Core software. This requirement doesn't include components deployed to the core device.
Minimum 96 MB RAM allocated to the Amazon 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.
Java Runtime Environment (JRE) version 8 or greater. Java must be available on the PATH 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 or OpenJDK long-term support versions. Version 8 or higher is required.
GNU C Library (glibc) version 2.25 or greater.
You must run the Amazon IoT Greengrass Core software as a root user. Use sudo, for example.
The root user that runs the Amazon 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.
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 Amazon 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.

Windows

The use of an Amazon Web Services Region that supports Amazon IoT Greengrass V2. For the list of supported Regions, see Amazon IoT Greengrass V2 endpoints and quotas in the Amazon Web Services General Reference.
Minimum 256 MB disk space available for the Amazon IoT Greengrass Core software. This requirement doesn't include components deployed to the core device.
Minimum 160 MB RAM allocated to the Amazon 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.
Java Runtime Environment (JRE) version 8 or greater. Java must be available on the PATH 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 or OpenJDK long-term support versions. Version 8 or higher is required..

Note
To use version 2.5.0 of the Greengrass nucleus, 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 Amazon IoT Greengrass Core software must be an administrator.
You must install the Amazon 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 Amazon IoT Greengrass Core software.
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.

Lambda function requirements

Your device must meet the following requirements to run Lambda functions:

A Linux-based operating system.
Your device must have the mkfifo shell command.
Your device must run the programming language libraries that a Lambda function requires. You must install the required libraries on the device and add them to the PATH environment variable. Greengrass supports all Lambda supported versions of Python, Node.js, and Java runtimes. Greengrass doesn't apply any additional restrictions on deprecated Lambda runtime versions. For more information about Amazon IoT Greengrass support for Lambda runtimes, see Run Amazon Lambda functions.
To run containerized Lambda functions, your device must meet the following requirements:
- Linux kernel version 4.4 or later.
- The kernel must support cgroups v1, and you must enable and mount the following cgroups:
  - The memory cgroup for Amazon IoT Greengrass to set the memory limit for containerized Lambda functions.
  - The devices cgroup for containerized Lambda functions to access system devices or volumes.
  The Amazon IoT Greengrass Core software doesn't support cgroups v2.
  
  To meet this requirement, boot the device with the following Linux kernel parameters.
```
cgroup_enable=memory cgroup_memory=1 systemd.unified_cgroup_hierarchy=0
```
  Tip
  On a Raspberry Pi, edit the /boot/cmdline.txt file to set the device's kernel parameters.
- You must enable the following Linux kernel configurations on the device:
  - Namespace:
    
    CONFIG_IPC_NS
    
    CONFIG_UTS_NS
    
    CONFIG_USER_NS
    
    CONFIG_PID_NS
  - Cgroups:
    
    CONFIG_CGROUP_DEVICE
    
    CONFIG_CGROUPS
    
    CONFIG_MEMCG
  - Others:
    
    CONFIG_POSIX_MQUEUE
    
    CONFIG_OVERLAY_FS
    
    CONFIG_HAVE_ARCH_SECCOMP_FILTER
    
    CONFIG_SECCOMP_FILTER
    
    CONFIG_KEYS
    
    CONFIG_SECCOMP
    
    CONFIG_SHMEM
  Tip
  Check the documentation for your Linux distribution to learn how to verify and set Linux kernel parameters. You can also use Amazon IoT Device Tester for Amazon IoT Greengrass to verify that your device meets these requirements. For more information, see Using Amazon IoT Device Tester for Amazon IoT Greengrass V2.

Feature considerations for Windows devices

Some Amazon 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 by operating system.

Set up an Amazon Web Services account

If you do not have an Amazon Web Services account, use the following procedure to create one.

To sign up for Amazon Web Services

Open http://www.amazonaws.cn/ and choose Sign Up.
Follow the on-screen instructions.

Secure IAM users

After you sign up for an Amazon Web Services account, safeguard your administrative user by turning on multi-factor authentication (MFA). For instructions, see Enable a virtual MFA device for an IAM user (console) in the IAM User Guide.

To give other users access to your Amazon Web Services account resources, create IAM users. To secure your IAM users, turn on MFA and only give the IAM users the permissions needed to perform their tasks.

For more information about creating and securing IAM users, see the following topics in the IAM User Guide:

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.

Next steps

Install the Amazon IoT Greengrass Core software