Install Amazon IoT Greengrass Core software with custom resource provisioning

Install the Java runtime, which Amazon IoT Greengrass Core software requires to run. We recommend that you use Amazon Corretto or OpenJDK long-term support versions. Version 8 or higher is required. The following commands show you how to install OpenJDK on your device.

When the installation completes, run the following command to verify that Java runs on your Linux device.

java -version

The command prints the version of Java that runs on the device. For example, on a Debian-based distribution, the output might look similar to the following sample.

openjdk version "11.0.9.1" 2020-11-04
OpenJDK Runtime Environment (build 11.0.9.1+1-post-Debian-1deb10u2)
OpenJDK 64-Bit Server VM (build 11.0.9.1+1-post-Debian-1deb10u2, mixed mode)

(Optional) Create the default system user and group that runs components on the device. You can also choose to let the Amazon IoT Greengrass Core software installer create this user and group during installation with the --component-default-user installer argument. For more information, see Installer arguments.

sudo useradd --system --create-home ggc_user
sudo groupadd --system ggc_group

Verify that the user that runs the Amazon IoT Greengrass Core software (typically root), has permission to run sudo with any user and any group.

1. Run the following command to open the /etc/sudoers file.

   sudo visudo

2. Verify that the permission for the user looks like the following example.

   root    ALL=(ALL:ALL) ALL

(Optional) To run containerized Lambda functions, you must enable cgroups v1, and you must enable and mount the memory and devices cgroups. If you don't plan to run containerized Lambda functions, you can skip this step.

To enable these cgroups options, boot the device with the following Linux kernel parameters.

cgroup_enable=memory cgroup_memory=1 systemd.unified_cgroup_hierarchy=0

For information about viewing and setting kernel parameters for your device, see the documentation for your operating system and boot loader. Follow the instructions to permanently set the kernel parameters.

Install all other required dependencies on your device as indicated by the list of requirements in Device requirements.

Install the Java runtime, which Amazon IoT Greengrass Core software requires to run. We recommend that you use Amazon Corretto or OpenJDK long-term support versions. Version 8 or higher is required.

Check whether Java is available on the PATH system variable, and add it if not. The LocalSystem account runs the Amazon IoT Greengrass Core software, so you must add Java to the PATH system variable instead of the PATH user variable for your user. Do the following:

1. Press the Windows key to open the start menu.

2. Type environment variables to search for the system options from the start menu.

3. In the start menu search results, choose Edit the system environment variables to open the System properties window.

4. Choose Environment variables... to open the Environment Variables window.

5. Under System variables, select Path, and then choose Edit. In the Edit environment variable window, you can view each path on a separate line.

6. Check if the path to the Java installation's bin folder is present. The path might look similar to the following example.

   C:\\Program Files\\Amazon Corretto\\jdk11.0.13_8\\bin

7. If the Java installation's bin folder is missing from Path, choose New to add it, and then choose OK.

Open the Windows Command Prompt (cmd.exe) as an administrator.

Create the default user in the LocalSystem account on the Windows device. Replace password with a secure password.

net user /add ggc_user password

Download and install the PsExec utility from Microsoft on the device.

Use the PsExec utility to store the user name and password for the default user in the Credential Manager instance for the LocalSystem account. Replace password with the user's password that you set earlier.

psexec -s cmd /c cmdkey /generic:ggc_user /user:ggc_user /pass:password

If the PsExec License Agreement opens, choose Accept to agree to the license and run the command.

On your core device, download the Amazon IoT Greengrass Core software to a file named greengrass-nucleus-latest.zip.

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

(Optional) To verify the Greengrass nucleus software signature

1. Use the following command to verify your Greengrass nucleus artifact's signature:

   Linux or Unix

   jarsigner -verify -certs -verbose greengrass-nucleus-latest.zip

   Windows Command Prompt (CMD)

   The file name might look different depending on the JDK version you install. Replace jdk17.0.6_10 with the JDK version you installed.

   "C:\\Program Files\\Amazon Corretto\\jdk17.0.6_10\\bin\\jarsigner.exe" -verify -certs -verbose greengrass-nucleus-latest.zip

   PowerShell

   The file name might look different depending on the JDK version you install. Replace jdk17.0.6_10 with the JDK version you installed.

   'C:\\Program Files\\Amazon Corretto\\jdk17.0.6_10\\bin\\jarsigner.exe' -verify -certs -verbose greengrass-nucleus-latest.zip

2. The jarsigner invocation yields output that indicates the results of the verification.

   1. If the Greengrass nucleus zip file is signed, the output contains the following statement:

      jar verified.

   2. If the Greengrass nucleus zip file isn't signed, the output contains the following statement:

      jar is unsigned.

3. If you provided the Jarsigner -certs option along with -verify and -verbose options, the output also includes detailed signer certificate information.

Unzip the Amazon IoT Greengrass Core software to a folder on your device. Replace GreengrassInstaller with the folder that you want to use.

(Optional) Run the following command to see the version of the Amazon IoT Greengrass Core software.

java -jar ./GreengrassInstaller/lib/Greengrass.jar --version

Check the version of the Amazon IoT Greengrass Core software.

java -jar ./GreengrassInstaller/lib/Greengrass.jar --version

Use a text editor to create a configuration file named config.yaml to provide to the installer.

For example, on a Linux-based system, you can run the following command to use GNU nano to create the file.

nano GreengrassInstaller/config.yaml

Copy the following YAML content into the file.

---
system:
  rootpath: "/greengrass/v2"
  # The following values are optional. Return them from the provisioning plugin or set them here.
  # certificateFilePath: ""
  # privateKeyPath: ""
  # rootCaPath: ""
  # thingName: ""
services:
  aws.greengrass.Nucleus:
    version: "2.12.3"
    configuration:
      # The following values are optional. Return them from the provisioning plugin or set them here.
      # awsRegion: ""
      # iotRoleAlias: ""
      # iotDataEndpoint: ""
      # iotCredEndpoint: ""
  com.example.CustomProvisioning:
    configuration:
      # You can specify configuration parameters to provide to your plugin.
      # pluginParameter: ""

Then, do the following:

---
system:
  rootpath: "/greengrass/v2"
  # The following values are optional. Return them from the provisioning plugin or set them here.
  # certificateFilePath: ""
  # privateKeyPath: ""
  # rootCaPath: ""
  # thingName: ""
services:
  aws.greengrass.Nucleus:
    version: "2.12.3"
    configuration:
      mqtt:
        port: 443
      greengrassDataPlanePort: 443
      networkProxy:
        noProxyAddresses: "http://192.168.0.1,www.example.com"
        proxy:
          url: "http://my-proxy-server:1100"
          username: "Mary_Major"
          password: "pass@word1357"
      # The following values are optional. Return them from the provisioning plugin or set them here.
      # awsRegion: ""
      # iotRoleAlias: ""
      # iotDataEndpoint: ""
      # iotCredEndpoint: ""
  com.example.CustomProvisioning:
    configuration:
      # You can specify configuration parameters to provide to your plugin.
      # pluginParameter: ""

Run the installer. Specify --trusted-plugin to provide your custom provisioning plugin, and specify --init-config to provide the configuration file.

If you specify --setup-system-service true, the installer prints Successfully set up Nucleus as a system service if it set up and ran the software as a system service. Otherwise, the installer doesn't output any message if it installs the software successfully.

Verify the installation by viewing the files in the root folder.

If the installation succeeded, the root folder contains several folders, such as config, packages, and logs.