Install the AWS IoT Greengrass Core software - AWS IoT Greengrass

Install the AWS IoT Greengrass Core software

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

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

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

 

Download and extract the AWS IoT Greengrass Core software package

Choose the AWS 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 AWS IoT Greengrass Core software.

 

Run the Greengrass device setup script

Run Greengrass device setup to configure your device, install the latest AWS 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 AWS IoT Greengrass Core software from an APT repository

You can use the Advanced Package Tool (APT) package management system to install the latest version of the AWS IoT Greengrass Core software on your core device. The APT repository provided by AWS IoT Greengrass includes the following packages:

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

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

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

You should be aware of the following considerations when you use the apt command to install the AWS IoT Greengrass Core software:

The AWS IoT Greengrass Core software is installed in the root directory.

The apt command installs the AWS IoT Greengrass Core software in a greengrass directory in the root file system. If /greengrass is already present, the command installs the new software version, but does not overwrite any group information or core configuration.

Over-the-air (OTA) updates are not supported.

You can use the apt installation option to upgrade the AWS IoT Greengrass Core software on your core device, but it doesn't support the safe update path provided by the AWS IoT Greengrass OTA update agent. The OTA update agent is a software component included with the AWS IoT Greengrass Core software package that's installed when you use the Download and extract a tar.gz file or Run the Greengrass device setup script installation options. The OTA update agent helps to guarantee that the core continues to function after an update by rolling back if the updates fails. For more information, see OTA updates of AWS IoT Greengrass Core software.

We recommend that you keep the keyring package updated.

Keeping the aws-iot-greengrass-keyring package updated allows you to receive updates for the GPG keys used to authenticate AWS IoT Greengrass APT repositories. It also allows you to upgrade the AWS IoT Greengrass Core software more easily. These trusted keys are installed in /etc/apt/trusted.gpg.d/. Public keys are valid for two years. If they expire, you must reconfigure the keyring package:

wget -O aws-iot-greengrass-keyring.deb https://d1onfpft10uf5o.cloudfront.net/greengrass-apt/downloads/aws-iot-greengrass-keyring.deb sudo dpkg -i aws-iot-greengrass-keyring.deb
Important

In the unlikely event that the keys managed by AWS IoT Greengrass become compromised, you must update the aws-iot-greengrass-keyring package to replace the compromised keys with new keys. For more information, contact AWS Customer Support.

Requirements

The following requirements apply for using apt to install the AWS IoT Greengrass Core software:

  • Your device must be running one of the following platforms:

    Architecture

    OS

    Distribution

    Armv8 (AArch64)

    Linux

    Arch Linux

    Armv7l

    Linux

    Raspbian Buster, 2019-07-10

    x86_64

    Linux

    Ubuntu 18.04

  • You must have root access on the device.

  • To complete the steps in the following procedures, the following shell commands must be installed on the device: sudo, wget or curl, dpkg, echo, unzip, and tar.

Using apt to install the AWS IoT Greengrass Core software

You can use the APT package management system to install the AWS IoT Greengrass Core software on your device. Some core configuration steps might be required before you install the software.

In the following procedures, run the commands in a terminal window on your device.

To configure your core

  1. If you're setting up AWS IoT Greengrass for the first time, you must configure your core. If the adduser or addgroup command is not available, use useradd or groupadd instead.

    1. Create the ggc_user and ggc_group system accounts.

      sudo adduser --system ggc_user sudo addgroup --system ggc_group
    2. Set up your core device certificates and keys and your core configuration file.

      1. Follow the steps in Configure AWS IoT Greengrass on AWS IoT to create a Greengrass group and register your core. This process also generates a security resources package that you download. The package is a tar.gz file that contains a core device certificate, public-private keys, and the core configuration file. The name of the file starts with a 10-digit hash (for example, c6973960cc-setup.tar.gz) that's also used for the certificate and key file names.

        Skip step 11 where you download the AWS IoT Greengrass Core software.

      2. Transfer the package to your core device and run the following command to install the security resources. Replace hash with the 10-digit hash from your tar.gz file.

        sudo mkdir -p /greengrass sudo tar -xzvf hash-setup.tar.gz -C /greengrass
      3. Download a root CA certificate. For information about choosing the appropriate root CA certificate, see Server authentication in the AWS IoT Core Developer Guide.

        The following example downloads AmazonRootCA1.pem. To use curl, replace wget -O in the command with curl.

        cd /greengrass/certs/ sudo wget -O root.ca.pem https://www.amazontrust.com/repository/AmazonRootCA1.pem

      These steps install the certificates and keys to /greengrass/certs and the configuration file to /greengrass/config. For more information, see AWS IoT Greengrass core configuration file.

  2. Download and run the dependency checker for AWS IoT Greengrass. The dependency checker makes sure you have all of the required dependencies for the AWS IoT Greengrass Core software. You can skip this step if you're upgrading from one patch version to another patch version (for example, v1.9.3 to v1.9.4).

    1. In the directory where you want to download the script, run the following command. To use curl, replace wget in the command with curl.

      mkdir greengrass-dependency-checker-GGCv1.10.x cd greengrass-dependency-checker-GGCv1.10.x wget https://github.com/aws-samples/aws-greengrass-samples/raw/master/greengrass-dependency-checker-GGCv1.10.x.zip unzip greengrass-dependency-checker-GGCv1.10.x.zip cd greengrass-dependency-checker-GGCv1.10.x sudo ./check_ggc_dependencies | more
    2. Where more appears, press the Spacebar key to page throught the output.

      • If stream manager is enabled in your Greengrass group, you must also install the Java 8 runtime before you deploy the group. This feature is enabled by default when you use the Default Group creation workflow in the AWS IoT Greengrass console to create a group.

      • You can install your target Lambda runtimes (for example, Python 3.7) and ignore the warnings about other missing optional runtime prerequisites.

      • You can ignore warnings about missing shell commands. These are required by the OTA update agent, which isn't included in this installation.

       

To install the AWS IoT Greengrass Core software

  1. Install the AWS IoT Greengrass keyring package and add the repository. To use curl, replace wget -O in the command with curl.

    wget -O aws-iot-greengrass-keyring.deb https://d1onfpft10uf5o.cloudfront.net/greengrass-apt/downloads/aws-iot-greengrass-keyring.deb sudo dpkg -i aws-iot-greengrass-keyring.deb echo "deb https://dnw9lb6lzp2d8.cloudfront.net stable main" | sudo tee /etc/apt/sources.list.d/greengrass.list
    Note

    If you keep the keyring package updated on your device, this step is required only the first time you install the AWS IoT Greengrass Core software from the APT repository.

  2. Update your list of packages.

    sudo apt update
  3. Install the AWS IoT Greengrass Core software.

    sudo apt install aws-iot-greengrass-core
  4. Start the Greengrass daemon. The following commands use systemd scripts installed with the aws-iot-greengrass-core package.

    systemctl start greengrass.service systemctl status greengrass.service

    If the output displays an Active state of active (running), the daemon started successfully.

 

To stop using the APT repository

If you want to stop using the APT repository for AWS IoT Greengrass, remove the packages and update your sources list.

Note

The remove command removes the packages, but not your configuration information. If you also want to permanently remove all configuration information (including device certificates, group information, and log files), replace remove in the following command with purge.

sudo apt remove aws-iot-greengrass-core aws-iot-greengrass-keyring sudo rm /etc/apt/sources.list.d/greengrass.list sudo apt update

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

 

Run AWS IoT Greengrass in a Docker container

AWS IoT Greengrass provides a Dockerfile and Docker images that make it easier for you to run the AWS IoT Greengrass Core software in a Docker container. For more information, see AWS 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 AWS IoT Greengrass in a snap

Currently, AWS IoT Greengrass snap software is available for AWS IoT Greengrass core version 1.8 only.

The AWS IoT Greengrass snap software download makes it possible for you to run a version of AWS IoT Greengrass with limited functionality on Linux cloud, desktop, and IoT environments through convenient containerized software packages. These packages, or snaps, contain the AWS IoT Greengrass Core software and its dependencies. You can download and use these packages on your Linux environments as-is.

The AWS IoT Greengrass snap allows you to run a version of AWS IoT Greengrass with limited functionality on your Linux environments. Currently, Java, Node.js, and native Lambda functions are not supported. Machine learning inference, connectors, and noncontainerized Lambda functions are also not supported.

Getting started with AWS IoT Greengrass snap

Because the prepackaged AWS IoT Greengrass snap is designed to use system defaults, you might need to perform these other steps:

  • The AWS IoT Greengrass snap is configured to use default Greengrass user and group configurations. This allows it to work easily with Greengrass groups or Lambda functions that run as root. If you need to use Greengrass groups or Lambda functions that do not run as root, update these configurations and add them to your system.

  • The AWS IoT Greengrass snap uses many interfaces that must be connected before the snap can operate normally. These interfaces are connected automatically during setup. If you use other options while you set up your snap, you might need to connect these interfaces manually.

For more information about the AWS IoT Greengrass snap and these modifications, see Greengrass Snap Release Notes.

  1. Install and upgrade snapd by running the following command in your device's terminal:

    sudo apt-get update && sudo apt-get upgrade snapd
  2. If you need to use Greengrass groups or Lambda functions that do not run as root, update your default Greengrass user and group configurations, and add them to your system. For more information about updating user and group configurations with AWS IoT Greengrass, see Setting the default access identity for Lambda functions in a group.

    • For the Ubuntu Core system:

      • To add the ggc_user user, use:

        sudo adduser --extrausers --system ggc_user
      • To add the ggc_group group, use:

        sudo addgroup --extrausers --system ggc_group
    • For the Ubuntu classic system:

      • To add the ggc_user user to an Ubuntu classic system, omit the --extrausers flag and use:

        sudo adduser --system ggc_user
      • To add the ggc_group to an Ubuntu classic system, omit the --extrausers flag and use:

        sudo addgroup --system ggc_group
  3. In your terminal, run the following command to install the Greengrass snap:

    sudo snap install aws-iot-greengrass
    Note

    You can also use the AWS IoT Greengrass snap download link to install the Greengrass snap locally. If you are installing locally from this file and do not have the associated assertions, use the --dangerous flag:

    sudo snap install --dangerous aws-iot-greengrass*.snap

    The --dangerous flag interferes with the AWS IoT Greengrass snap's ability to connect its required interfaces. If you use this flag, you must manually connect the required interfaces using the snap connect command. For more information, see Greengrass Snap Release Notes.

  4. After the snap is installed, run the following command to add your Greengrass certificate and configuration files:

    sudo snap set aws-iot-greengrass gg-certs=/path-to-the-certs/22e592db.tgz
    Note

    If necessary, you can troubleshoot issues by viewing the AWS IoT Greengrass core logs, particularly runtime.log. You can print the contents of runtime.log to your terminal by running the following command:

    sudo cat /var/snap/aws-iot-greengrass/current/ggc-writable/var/log/system/runtime.log
  5. Run the following command to validate that your setup is functioning correctly:

    $ snap services aws-iot-greengrass

    You should see the following response:

    Service Startup Current Notes aws-iot-greengrass.greengrassd enabled active -

Your Greengrass setup is now complete. You can now use the AWS IoT Greengrass console, AWS REST API, or AWS CLI to deploy the Greengrass groups associated with this snap. For information about using the console to deploy a Greengrass group, see the Deploy cloud configurations to an AWS IoT Greengrass core device. For information about using the CLI or REST API to deploy a Greengrass group, see CreateDeployment in the AWS IoT Greengrass API Reference.

For more information about configuring local resource access with snap AppArmor confinement, using the snapd REST API, and configuring snap interfaces, see Greengrass Snap Release Notes.

Archive an AWS IoT Greengrass Core software installation

When you upgrade to a new version of the AWS 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 AWS 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 AWS 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.