Install the Amazon IoT Greengrass Core software - 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.

Amazon IoT Greengrass Version 1 no longer receives feature updates, and will receive only security patches and bug fixes until June 30, 2023. For more information, see the Amazon IoT Greengrass V1 maintenance policy. We strongly recommend that you migrate to Amazon IoT Greengrass Version 2, which adds significant new features and support for additional platforms.

Install the Amazon IoT Greengrass Core software

The Amazon IoT Greengrass Core software extends Amazon functionality onto an Amazon IoT Greengrass core device, making it possible for local devices to act locally on the data they generate.

Amazon IoT Greengrass provides several options for installing the Amazon IoT Greengrass Core software:

Amazon IoT Greengrass also provides containerized environments that run the Amazon IoT Greengrass Core software.

 

Download and extract the Amazon IoT Greengrass Core software package

Choose the Amazon IoT Greengrass Core software for your platform to download as a tar.gz file and extract on your device. You can download recent versions of the software. For more information, see Amazon IoT Greengrass Core software.

 

Run the Greengrass device setup script

Run Greengrass device setup to configure your device, install the latest Amazon IoT Greengrass Core software version, and deploy a Hello World Lambda function in minutes. For more information, see Quick start: Greengrass device setup.

 

Install the Amazon IoT Greengrass Core software from an APT repository

Important

As of February 11, 2022, you can no longer install or update the Amazon IoT Greengrass Core software from an APT repository. On devices where you added the Amazon IoT Greengrass repository, you must remove the repository from the sources list. Devices that run the software from the APT repository will continue to operate normally. We recommend that you update the Amazon IoT Greengrass Core software using tar files.

The APT repository provided by Amazon IoT Greengrass includes the following packages:

  • aws-iot-greengrass-core. Installs the Amazon IoT Greengrass Core software.

  • aws-iot-greengrass-keyring. Installs the GnuPG (GPG) keys used to sign the Amazon IoT Greengrass package repository.

    By downloading this software, you agree to the Greengrass Core Software License Agreement.

Use systemd scripts to manage the Greengrass daemon lifecycle

The aws-iot-greengrass-core package also installs systemd scripts that you can use to manage the Amazon IoT Greengrass Core software (daemon) lifecycle.

  • To start the Greengrass daemon during boot:

    systemctl enable greengrass.service
  • To start the Greengrass daemon:

    systemctl start greengrass.service
  • To stop the Greengrass daemon:

    systemctl stop greengrass.service
  • To check the status of the Greengrass daemon:

    systemctl status greengrass.service

Uninstall the Amazon IoT Greengrass core software using the APT repository

When you uninstall the Amazon IoT Greengrass core software, you can choose whether to preserve or remove the Amazon IoT Greengrass core software's configuration information, such as device certificates, group information, and log files.

To uninstall the Amazon IoT Greengrass core software and preserve configuration information

  • Run the following command to remove the Amazon IoT Greengrass core software packages and preserve configuration information in the /greengrass folder.

    sudo apt remove aws-iot-greengrass-core aws-iot-greengrass-keyring

To uninstall the Amazon IoT Greengrass core software and remove configuration information

  1. Run the following command to remove the Amazon IoT Greengrass core software packages and remove configuration information from the /greengrass folder.

    sudo apt purge aws-iot-greengrass-core aws-iot-greengrass-keyring
  2. Remove the Amazon IoT Greengrass core software repository from your sources list. For more information, see Remove the Amazon IoT Greengrass core software repository sources.

Remove the Amazon IoT Greengrass core software repository sources

You can remove the Amazon IoT Greengrass core software repository sources when you no longer need to install or update the Amazon IoT Greengrass core software from the APT repository. After February 11, 2022, you must remove the repository from your sources list to avoid an error when you run apt update.

To remove the APT repository from the sources list

  • Run the following commands to remove the Amazon IoT Greengrass core software repository from the sources list.

    sudo rm /etc/apt/sources.list.d/greengrass.list sudo apt update

Run Amazon IoT Greengrass in a Docker container

Amazon IoT Greengrass provides a Dockerfile and Docker images that make it easier for you to run the Amazon IoT Greengrass Core software in a Docker container. For more information, see Amazon IoT Greengrass Docker software.

Note

You can also run a Docker application on a Greengrass core device. To do so, use the Greengrass Docker application deployment connector.

 

Run Amazon IoT Greengrass in a snap

Amazon IoT Greengrass snap 1.11.x enables you to run a limited version of Amazon IoT Greengrass through convenient software packages, along with all necessary dependencies, in a containerized environment.

Note

The Amazon IoT Greengrass snap is available for Amazon IoT Greengrass Core software v1.11.x. Amazon IoT Greengrass doesn’t provide a snap for v1.10.x. Unsupported versions don't receive bug fixes or updates.

The Amazon IoT Greengrass snap doesn't support connectors and machine learning (ML) inference.

Snap concepts

The following are essential snap concepts to help you understand how to use the Amazon IoT Greengrass snap:

Channel

A snap component that defines which version of a snap is installed and tracked for updates. Snaps are automatically updated to the latest version of the current channel.

Interface

A snap component that grants access to resources, such as networks and user files.

To run the Amazon IoT Greengrass snap, the following interfaces must be connected. Note that greengrass-support-no-container must be connected first and never disconnected.

- greengrass-support-no-container - hardware-observe - home-for-hooks - hugepages-control - log-observe - mount-observe - network - network-bind - network-control - process-control - system-observe

The other interfaces are optional. If your Lambda functions require access to specific resources, you might need to connect to the appropriate interfaces.

Refresh

Snaps are automatically updated. The snapd daemon is the snap package manager that checks for updates four times a day by default. Each update check is called a refresh. When a refresh occurs, the daemon stops, the snap gets updated, and then the daemon restarts.

For more information, see the Snapcraft website.

What's new with Amazon IoT Greengrass snap v1.11.x

The following describes what's new and changed with the version 1.11.x of the Amazon IoT Greengrass snap.

  • This version supports only the snap_daemon user, exposed as user ID (UID) and group (GID) 584788.

  • This version supports only noncontainerized Lambda functions.

    Important

    Because noncontainerized Lambda functions must share the same user (snap_daemon), the Lambda functions have no isolation from each other. For more information, see Controlling execution of Greengrass Lambda functions by using group-specific configuration.

  • This version supports C, C++, Java 8, Node.js 12.x, Python 2.7, Python 3.7, and Python 3.8 runtimes.

    Note

    To avoid redundant Python runtimes, Python 3.7 Lambda functions actually run the Python 3.8 runtime.

Getting started with Amazon IoT Greengrass snap

The following procedure helps you install and configure the Amazon IoT Greengrass snap on your device.

Requirements

To run the Amazon IoT Greengrass snap, you must do the following:

  • Run the Amazon IoT Greengrass snap on a supported Linux distribution, such as Ubuntu, Linux Mint, Debian, and Fedora.

  • Install the snapd daemon on your device. The snapd daemon including the snap tool manages the snap environment on your device.

For the list of supported Linux distributions and installation instructions, see Installing snapd in the Snap documentation.

Install and configure the Amazon IoT Greengrass snap

The following tutorial shows you how to install and configure the Amazon IoT Greengrass snap on your device.

Note
  • Although this tutorial uses an Amazon EC2 instance (x86 t2.micro Ubuntu 20.04), you can run the Amazon IoT Greengrass snap with physical hardware, such as a Raspberry Pi.

  • The snapd daemon is preinstalled on Ubuntu.

  1. Install the core18 snap by running the following command in your device's terminal:

    sudo snap install core18

    The core18 snap is a base snap that provides a runtime environment with commonly used libraries. This snap is built from Ubuntu 18.04 LTS.

  2. Upgrade snapd by running the following command:

    sudo snap install --channel=edge snapd; sudo snap refresh --channel=edge snapd
  3. Run the snap list command to check if you have the Amazon IoT Greengrass snap installed.

    The following example response shows that snapd is installed, but aws-iot-greengrass isn't.

    Name Version Rev Tracking Publisher Notes amazon-ssm-agent 3.0.161.0 2996 latest/stable/… aws✓ classic core 16-2.48 10444 latest/stable canonical✓ core core18 20200929 1932 latest/stable canonical✓ base lxd 4.0.4 18150 4.0/stable/… canonical✓ - snapd 2.48+git548.g929ccfb 10526 latest/edge canonical✓ snapd
  4. Choose one of the following options to install Amazon IoT Greengrass snap 1.11.x.

    • To install the Amazon IoT Greengrass snap, run the following command:

      sudo snap install aws-iot-greengrass

      Example response:

      aws-iot-greengrass 1.11.5 from Amazon Web Services (aws) installed
    • To migrate from an earlier version to v1.11.x or update to the latest available patch version, run the following command:

      sudo snap refresh --channel=1.11.x aws-iot-greengrass

    Like other snaps, the Amazon IoT Greengrass snap uses channels to manage minor versions. Snaps are automatically updated to the latest available version of the current channel. For examples, if you specify --channel=1.11.x, your Amazon IoT Greengrass snap is updated to v1.11.5.

    You can run the snap info aws-iot-greengrass command to get the list of available channels for Amazon IoT Greengrass.

  5. To access specific resources that your Lambda functions need, you can connect to additional interfaces.

    Run the following command to get the list of Amazon IoT Greengrass snap supported interfaces:

    snap connections aws-iot-greengrass

    Example response:

    Interface Plug Slot Notes camera aws-iot-greengrass:camera - - dvb aws-iot-greengrass:dvb - - gpio aws-iot-greengrass:gpio - - gpio-memory-control aws-iot-greengrass:gpio-memory-control - - greengrass-support aws-iot-greengrass:greengrass-support-no-container :greengrass-support - hardware-observe aws-iot-greengrass:hardware-observe :hardware-observe manual hardware-random-control aws-iot-greengrass:hardware-random-control - - home aws-iot-greengrass:home-for-greengrassd - - home aws-iot-greengrass:home-for-hooks :home manual hugepages-control aws-iot-greengrass:hugepages-control :hugepages-control manual i2c aws-iot-greengrass:i2c - - iio aws-iot-greengrass:iio - - joystick aws-iot-greengrass:joystick - - log-observe aws-iot-greengrass:log-observe :log-observe manual mount-observe aws-iot-greengrass:mount-observe :mount-observe manual network aws-iot-greengrass:network :network - network-bind aws-iot-greengrass:network-bind :network-bind - network-control aws-iot-greengrass:network-control :network-control - opengl aws-iot-greengrass:opengl :opengl - optical-drive aws-iot-greengrass:optical-drive :optical-drive - process-control aws-iot-greengrass:process-control :process-control - raw-usb aws-iot-greengrass:raw-usb - - removable-media aws-iot-greengrass:removable-media - - serial-port aws-iot-greengrass:serial-port - - spi aws-iot-greengrass:spi - - system-observe aws-iot-greengrass:system-observe :system-observe -

    If you see a hyphen (-) in the Slot column, the corresponding interface isn't connected.

  6. Follow Installing the Amazon IoT Greengrass Core software to create an Amazon IoT thing, a Greengrass group, security resources that enable secure communications with Amazon IoT, and the Amazon IoT Greengrass Core software configuration file. The configuration file, config.json, contains configuration specific to your Greengrass core, such as the location of certificate files and the Amazon IoT device data endpoint.

    Note

    If you downloaded the file to a different device, follow this step to transfer the files to the Amazon IoT Greengrass core device.

  7. For the Amazon IoT Greengrass snap, make sure that you update the config.json file, as shown in the following:

    • Replace each instance of certificateId with the certificate ID in the name of the certificate and key files.

    • If you downloaded a different Amazon root CA certificate than Amazon Root CA 1, replace each instance of AmazonRootCA1.pem with the name of the Amazon root CA file.

    { ... "crypto" : { "principals" : { "SecretsManager" : { "privateKeyPath" : "file:///snap/aws-iot-greengrass/current/greengrass/certs/certificateId-private.pem.keyy" }, "IoTCertificate" : { "privateKeyPath" : "file:///snap/aws-iot-greengrass/current/greengrass/certs/certificateId-private.pem.key", "certificatePath" : "file:///snap/aws-iot-greengrass/current/greengrass/certs/certificateId-certificate.pem.crt" } }, "caPath" : "file:///snap/aws-iot-greengrass/current/greengrass/certs/AmazonRootCA1.pem" }, "writeDirectory": "/var/snap/aws-iot-greengrass/current/ggc-write-directory", "pidFileDirectory": "/var/snap/aws-iot-greengrass/current/pidFileDirectory" }
  8. Run the following command to add your Amazon IoT Greengrass certificate and configuration files:

    sudo snap set aws-iot-greengrass gg-certs=/home/ubuntu/my-certs

Deploying a Lambda function

This section shows you how to deploy a customer managed Lambda function on the Amazon IoT Greengrass snap.

Important

Amazon IoT Greengrass snap v1.11 only supports noncontainerized Lambda functions.

  1. Run the following command to start the Amazon IoT Greengrass daemon:

    sudo snap start aws-iot-greengrass

    Example response:

    Started.
  2. Run the following command to confirm that the daemon is running:

    snap services aws-iot-greengrass.greengrassd

    Example response:

    Service Startup Current Notes aws-iot-greengrass.greengrassd disabled active -
  3. Follow Module 3 (part 1): Lambda functions on Amazon IoT Greengrass to create and deploy a Hello World Lambda function. However, before you deploy the Lambda function, complete the next step.

  4. Make sure that your Lambda function run as the snap_daemon user and in the no container mode. To update the settings of your Greengrass group, do the following in the Amazon IoT Greengrass console:

    1. Sign in to the Amazon IoT Greengrass console.

    2. In the Amazon IoT console navigation pane, under Manage, expand Greengrass devices, and then choose Groups (V1).

    3. Under Greengrass groups, choose the target group.

    4. On the group configuration page, in the navigation pane, choose the Lambda functions tab.

    5. Under Default Lambda function runtime environment, choose Edit, and do the following:

      1. For Default system user and group, choose Another user ID/group ID, and then enter 584788 for both System user ID (number) and System group ID (number).

      2. For Default Lambda function containerization, choose No container.

      3. Choose Save.

Stopping the Amazon IoT Greengrass daemon

You can use the snap stop command to stop a service.

To stop the Amazon IoT Greengrass daemon, run the following command:

sudo snap stop aws-iot-greengrass

The command should return Stopped..

To check if you successfully stopped the snap, run the following command:

snap services aws-iot-greengrass.greengrassd

Example response:

Service Startup Current Notes aws-iot-greengrass.greengrassd disabled inactive -

Uninstalling the Amazon IoT Greengrass snap

To uninstall the Amazon IoT Greengrass snap, run the following command:

sudo snap remove aws-iot-greengrass

Example response:

aws-iot-greengrass removed

Troubleshooting the Amazon IoT Greengrass snap

Use the following information to help troubleshoot issues with the Amazon IoT Greengrass snap.

Got permission denied errors.

Solution: Permission denied errors are often because of missing interfaces. For the list of missing interfaces and detailed troubleshooting information, you can use the snappy-debug tool.

Run the following command to install the tool.

sudo snap install snappy-debug

Example response:

snappy-debug 0.36-snapd2.45.1 from Canonical✓ installed

Run the sudo snappy-debug command in a separate terminal session. The operation continues until a permission denied error occurs.

For example, if your Lambda function tries to read a file in the $HOME directory, you may get the following response:

INFO: Following '/var/log/syslog'. If have dropped messages, use: INFO: $ sudo journalctl --output=short --follow --all | sudo snappy-debug kernel.printk_ratelimit = 0 = AppArmor = Time: Dec 6 04:48:26 Log: apparmor="DENIED" operation="mknod" profile="snap.aws-iot-greengrass.greengrassd" name="/home/ubuntu/my-file.txt" pid=12345 comm="touch" requested_mask="c" denied_mask="c" fsuid=0 ouid=0 File: /home/ubuntu/my-file.txt (write) Suggestion: * add 'home' to 'plugs'

This example shows that creating the /home/ubuntu/my-file.txt file caused the permission error. It also suggests that you add home to plugs. However, this sugguestion is not applicable. The home-for-greengrassd and home-for-hooks plugs are only given the read-only access.

For more information, see The snappy-debug snap in the Snap documentation.

error: cannot perform the following tasks: - Run service command "start" for services ["greengrassd"] of snap "aws-iot-greengrass" ([start snap.aws-iot-greengrass.greengrassd.service] failed with exit status 1: Job for snap.aws-iot-greengrass.greengrassd.service failed because the control process exited with error code. See "systemctl status snap.aws-iot-greengrass.greengrassd.service" and "journalctl -xe" for details.)

Solution: You might see this error when the snap start aws-iot-greengrass command fails to start the Amazon IoT Greengrass Core software.

For more troubleshooting information, run the following command:

sudo snap run aws-iot-greengrass.greengrassd

Example response:

Couldn't find /snap/aws-iot-greengrass/44/greengrass/config/config.json.

This examples shows that Amazon IoT Greengrass couldn't find the config.json file. You might check the configuration and certificate files.

/var/snap/aws-iot-greengrass/current/ggc-write-directory/packages/1.11.5/rootfs/merged is not an absolute path or is a symlink.

Solution: The Amazon IoT Greengrass snap supports only noncontainerized Lambda functions. Make sure that you run your Lambda functions in the no container mode. For more information, see Considerations when choosing Lambda function containerization in the Amazon IoT Greengrass Version 1 Developer Guide.

The snapd daemon failed to restart after you ran the sudo snap refresh snapd command.

Solution: Follow steps 6 through 8 in Install and configure the Amazon IoT Greengrass snap to add the Amazon IoT Greengrass certificate and configuration files to the Amazon IoT Greengrass snap.

Archive an Amazon IoT Greengrass Core software installation

When you upgrade to a new version of the Amazon IoT Greengrass Core software, you can archive the currently installed version. This preserves your current installation environment so you can test a new software version on the same hardware. This also makes it easy to roll back to your archived version for any reason.

To archive the current installation and install a new version

  1. Download the Amazon IoT Greengrass Core software installation package that you want to upgrade to.

  2. Copy the package to the destination core device. For instructions that show how to transfer files, see this step.

    Note

    You copy your current certificates, keys, and configuration file to the new installation later.

    Run the commands in the following steps in your core device terminal.

  3. Make sure that the Greengrass daemon is stopped on the core device.

    1. To check whether the daemon is running:

      ps aux | grep -E 'greengrass.*daemon'

      If the output contains a root entry for /greengrass/ggc/packages/ggc-version/bin/daemon, then the daemon is running.

      Note

      This procedure is written with the assumption that the Amazon IoT Greengrass Core software is installed in the /greengrass directory.

    2. To stop the daemon:

      cd /greengrass/ggc/core/ sudo ./greengrassd stop
  4. Move the current Greengrass root directory to a different directory.

    sudo mv /greengrass /greengrass_backup
  5. Untar the new software on the core device. Replace the os-architecture and version placeholders in the command.

    sudo tar –zxvf greengrass-os-architecture-version.tar.gz –C /
  6. Copy the archived certificates, keys, and configuration file to the new installation.

    sudo cp /greengrass_backup/certs/* /greengrass/certs sudo cp /greengrass_backup/config/* /greengrass/config
  7. Start the daemon:

    cd /greengrass/ggc/core/ sudo ./greengrassd start

Now, you can make a group deployment to test the new installation. If something fails, you can restore the archived installation.

To restore the archived installation

  1. Stop the daemon.

  2. Delete the new /greengrass directory.

  3. Move the /greengrass_backup directory back to /greengrass.

  4. Start the daemon.