Configure the AWS IoT Greengrass Core software

The AWS IoT Greengrass Core software provides options that you can use to configure the software. You can create deployments to configure the AWS IoT Greengrass Core software on each core device.

Deploy the Greengrass nucleus component

AWS IoT Greengrass provides the AWS IoT Greengrass Core software as a component that you can deploy to your Greengrass core devices. You can create a deployment to apply the same configuration to multiple Greengrass core devices. For more information, see Greengrass nucleus and Update the AWS IoT Greengrass Core software (OTA).

Configure the Greengrass nucleus as a system service

You must configure the AWS IoT Greengrass Core software as a system service in your device's init system to do the following:

Configure the nucleus as a system service (Linux)

Linux devices support different init systems, such as initd, systemd, and SystemV. You use the --setup-system-service true argument when you install the AWS IoT Greengrass Core software to start the nucleus as a system service and configure it to launch when the device boots. The installer configures the AWS IoT Greengrass Core software as a system service with systemd.

You can also manually configure the nucleus to run as a system service. The following example is a service file for systemd.

[Unit]
Description=Greengrass Core

[Service]
Type=simple
PIDFile=/greengrass/v2/alts/loader.pid
RemainAfterExit=no
Restart=on-failure
RestartSec=10
ExecStart=/bin/sh /greengrass/v2/alts/current/distro/bin/loader

[Install]
WantedBy=multi-user.target

After you configure the system service, you can run the following commands to configure starting the device on boot and to start or stop the AWS IoT Greengrass Core software.

Configure the nucleus as a system service (Windows)

You use the --setup-system-service true argument when you install the AWS IoT Greengrass Core software to start the nucleus as a Windows service and configure it to launch when the device boots.

After you configure the service, you can run the following commands to configure starting the device on boot and to start or stop the AWS IoT Greengrass Core software. You must run Command Prompt or PowerShell as an administrator to run these commands.

Windows Command Prompt (CMD)

• To check the status of the service

  sc query "greengrass"

• To enable the nucleus to start when the device boots.

  sc config "greengrass" start=auto

• To stop the nucleus from starting when the device boots.

  sc config "greengrass" start=disabled

• To start the AWS IoT Greengrass Core software.

  sc start "greengrass"

• To stop the AWS IoT Greengrass Core software.

  sc stop "greengrass"

  Note

  On Windows devices, the AWS IoT Greengrass Core software ignores this shutdown signal while it shuts down Greengrass component processes. If the AWS IoT Greengrass Core software ignores the shutdown signal when you run this command, wait a few seconds, and try again.

PowerShell

• To check the status of the service

  Get-Service -Name "greengrass"

• To enable the nucleus to start when the device boots.

  Set-Service -Name "greengrass" -Status stopped -StartupType automatic

• To stop the nucleus from starting when the device boots.

  Set-Service -Name "greengrass" -Status stopped -StartupType disabled

• To start the AWS IoT Greengrass Core software.

  Start-Service -Name "greengrass"

• To stop the AWS IoT Greengrass Core software.

  Stop-Service -Name "greengrass"

  Note

  On Windows devices, the AWS IoT Greengrass Core software ignores this shutdown signal while it shuts down Greengrass component processes. If the AWS IoT Greengrass Core software ignores the shutdown signal when you run this command, wait a few seconds, and try again.

Control memory allocation with JVM options

If you're running AWS IoT Greengrass on a device with limited memory, you can use Java virtual machine (JVM) options to control the maximum heap size, garbage collection modes, and compiler options, which control the amount of memory that AWS IoT Greengrass Core software uses. The heap size in the JVM determines how much memory an application can use before garbage collection occurs, or before the application runs out of memory. The maximum heap size specifies the maximum amount of memory the JVM can allocate when expanding the heap during heavy activity.

To control memory allocation, create a new deployment or revise an existing deployment that includes the nucleus component, and specify your JVM options in the jvmOptions configuration parameter in the nucleus component configuration.

Depending on your requirements, you can run AWS IoT Greengrass Core software with reduced memory allocation or with minimum memory allocation.

Reduced memory allocation

To run AWS IoT Greengrass Core software with reduced memory allocation, we recommend that you use the following example configuration merge update to set JVM options in your nucleus configuration:

{
  "jvmOptions": "-XX:+UseSerialGC -XX:TieredStopAtLevel=1"
}

Minimum memory allocation

To run AWS IoT Greengrass Core software with minimum memory allocation, we recommend that you use the following example configuration merge update to set JVM options in your nucleus configuration:

{
  "jvmOptions": "-Xmx32m -XX:+UseSerialGC -Xint"
}

These example configuration merge updates use the following JVM options:

For information about creating configuration merge updates, see Update component configurations.

Configure the user that runs components

The AWS IoT Greengrass Core software can run component processes as a system user and group different from the one that runs the software. This increases security, because you can run the AWS IoT Greengrass Core software as root, or as an administrator user, without giving those permissions to components that run on the core device.

The following table indicates which types of components the AWS IoT Greengrass Core software can run as a user that you specify. For more information, see Component types.

You must create the component user before you can specify it in a deployment configuration. On Windows-based devices, you must also store the user name and password for the user in the credential manager instance of the LocalSystem account. For more information, see Set up a component user on Windows devices.

When you configure the component user on a Linux-based device, you can optionally also specify a group. You specify the user and group separated by a colon (:) in the following format: user:group. If you don't specify a group, the AWS IoT Greengrass Core software defaults to the primary group of the user. You can use either the name or the ID to identify the user and group.

On Linux-based devices, you can also run components as a system user that doesn't exist, also called an unknown user, to increase security. A Linux process can signal any other process that is run by the same user. An unknown user doesn't run other processes, so you can run components as an unknown user to prevent components from signaling other components on the core device. To run components as an unknown user, specify a user ID that doesn't exist on the core device. You can also specify a group ID that doesn't exist to run as an unknown group.

You can configure the user for each component and for each core device.

Set up a component user on Windows devices

Configure the default component user

You can use a deployment to configure the default user on a core device. In this deployment, you update the nucleus component configuration.

Create a deployment that specifies the following configuration update for the aws.greengrass.Nucleus component.

Linux

{
  "runWithDefault": {
    "posixUser": "ggc_user:ggc_group"
  }
}

Windows

{
  "runWithDefault": {
    "windowsUser": "ggc_user"
  }
}

Note

The user that you specify must exist, and the user name and password for this user must be stored in the credential manager instance of the LocalSystem account on your Windows device. For more information, see Set up a component user on Windows devices.

The following example defines a deployment for a Linux-based device that configures ggc_user as the default user and ggc_group as the default group. The merge configuration update requires a serialized JSON object.

{
  "components": {
    "aws.greengrass.Nucleus": {
      "version": "2.13.0",
      "configurationUpdate": {
        "merge": "{\"runWithDefault\":{\"posixUser\":\"ggc_user:ggc_group\"}}"
      }
    }
  }
}

Configure system resource limits for components

You can configure the maximum amount of CPU and RAM usage that each component's processes can use on the core device.

The following table shows the types of components that support system resource limits. For more information, see Component types.

You can configure system resource limits for each component and for each core device.

Configure default system resource limits

You can deploy the Greengrass nucleus component to configure the default system resource limits for a core device. To configure the default system resource limits, create a deployment that specifies the following configuration update for the aws.greengrass.Nucleus component.

{
  "runWithDefault": {
    "systemResourceLimits": {
      "cpu": cpuTimeLimit,
      "memory": memoryLimitInKb
    }
  }
}

The following example defines a deployment that configures the CPU time limit to 2, which is equivalent to 50% usage on a device with 4 CPU cores. This example also configures the memory usage to 100 MB.

{
  "components": {
    "aws.greengrass.Nucleus": {
      "version": "2.13.0",
      "configurationUpdate": {
        "merge": "{\"runWithDefault\":{\"systemResourceLimits\":\"cpus\":2,\"memory\":102400}}}"
      }
    }
  }
}

Connect on port 443 or through a network proxy

AWS IoT Greengrass core devices communicate with AWS IoT Core using the MQTT messaging protocol with TLS client authentication. By convention, MQTT over TLS uses port 8883. However, as a security measure, restrictive environments might limit inbound and outbound traffic to a small range of TCP ports. For example, a corporate firewall might open port 443 for HTTPS traffic, but close other ports that are used for less common protocols, such as port 8883 for MQTT traffic. Other restrictive environments might require all traffic to go through a proxy before connecting to the internet.

To enable communication in these scenarios, AWS IoT Greengrass provides the following configuration options:

Configure MQTT over port 443

You can configure MQTT over port 443 on existing core devices or when you install the AWS IoT Greengrass Core software on a new core device.

Configure MQTT over port 443 on existing core devices

You can use a deployment to configure MQTT over port 443 on a single core device or a group of core devices. In this deployment, you update the nucleus component configuration. The nucleus restarts when you update its mqtt configuration.

To configure MQTT over port 443, create a deployment that specifies the following configuration update for the aws.greengrass.Nucleus component.

{
  "mqtt": {
    "port": 443
  }
}

The following example defines a deployment that configures MQTT over port 443. The merge configuration update requires a serialized JSON object.

{
  "components": {
    "aws.greengrass.Nucleus": {
      "version": "2.13.0",
      "configurationUpdate": {
        "merge": "{\"mqtt\":{\"port\":443}}"
      }
    }
  }
}

Configure MQTT over port 443 during installation

You can configure MQTT over port 443 when you install the AWS IoT Greengrass Core software on a core device. Use the --init-config installer argument to configure MQTT over port 443. You can specify this argument when you install with manual provisioning, fleet provisioning, or custom provisioning.

Configure HTTPS over port 443

This feature requires Greengrass nucleus v2.0.4 or later.

You can configure HTTPS over port 443 on existing core devices or when you install the AWS IoT Greengrass Core software on a new core device.

Configure HTTPS over port 443 on existing core devices

You can use a deployment to configure HTTPS over port 443 on a single core device or a group of core devices. In this deployment, you update the nucleus component configuration.

To configure HTTPS over port 443, create a deployment that specifies the following configuration update for the aws.greengrass.Nucleus component.

{
  "greengrassDataPlanePort": 443
}

The following example defines a deployment that configures HTTPS over port 443. The merge configuration update requires a serialized JSON object.

{
  "components": {
    "aws.greengrass.Nucleus": {
      "version": "2.13.0",
      "configurationUpdate": {
        "merge": "{\"greengrassDataPlanePort\":443}"
      }
    }
  }
}

Configure HTTPS over port 443 during installation

You can configure HTTPS over port 443 when you install the AWS IoT Greengrass Core software on a core device. Use the --init-config installer argument to configure HTTPS over port 443. You can specify this argument when you install with manual provisioning, fleet provisioning, or custom provisioning.

Configure a network proxy

Follow a procedure in this section to configure Greengrass core devices to connect to the internet through an HTTP or HTTPS network proxy. For more information about the endpoints and ports that core devices use, see Allow device traffic through a proxy or firewall.

Configure a network proxy on existing core devices

You can use a deployment to configure a network proxy on a single core device or a group of core devices. In this deployment, you update the nucleus component configuration. The nucleus restarts when you update its networkProxy configuration.

To configure a network proxy, create a deployment for the aws.greengrass.Nucleus component that merges the following configuration update. This configuration update contains the networkProxy object.

{
  "networkProxy": {
    "noProxyAddresses": "http://192.168.0.1,www.example.com",
    "proxy": {
      "url": "https://my-proxy-server:1100"
    }
  }
}

The following example defines a deployment that configures a network proxy. The merge configuration update requires a serialized JSON object.

{
  "components": {
    "aws.greengrass.Nucleus": {
      "version": "2.13.0",
      "configurationUpdate": {
        "merge": "{\"networkProxy\":{\"noProxyAddresses\":\"http://192.168.0.1,www.example.com\",\"proxy\":{\"url\":\"https://my-proxy-server:1100\",\"username\":\"Mary_Major\",\"password\":\"pass@word1357\"}}}"
      }
    }
  }
}

Configure a network proxy during installation

You can configure a network proxy when you install the AWS IoT Greengrass Core software on a core device. Use the --init-config installer argument to configure the network proxy. You can specify this argument when you install with manual provisioning, fleet provisioning, or custom provisioning.

Enable the core device to trust an HTTPS proxy

When you configure a core device to use an HTTPS proxy, you must add the proxy server certificate chain to the core device's to enable it to trust the HTTPS proxy. Otherwise, the core device might encounter errors when it tries to route traffic through the proxy. Add the proxy server CA certificate to the core device's Amazon root CA certificate file.

The networkProxy object

Use the networkProxy object to specify information about the network proxy. This object contains the following information:

Use a device certificate signed by a private CA

If you are using a custom private certificate authority (CA), you must set the Greengrass nucleus' greengrassDataPlaneEndpoint to iotdata. You can set this option during deployment or installation using the --init-config installer argument.

You can customize the Greengrass data plane endpoint where the device connects. You can set this configuration option to iotdata to set the Greengrass data plane endpoint to the same endpoint as the IoT data endpoint, which you can specify with the iotDataEndpoint.

Configure MQTT timeouts and cache settings

In the AWS IoT Greengrass environment, components can use MQTT to communicate with AWS IoT Core. The AWS IoT Greengrass Core software manages MQTT messages for components. When the core device loses connection to the AWS Cloud, the software caches MQTT messages to retry later when the connection restores. You can configure settings such as message timeouts and the size of the cache. For more information, see the mqtt and mqtt.spooler configuration parameters of the Greengrass nucleus component.

AWS IoT Core imposes service quotas on its MQTT message broker. These quotas might apply to messages that you send between core devices and AWS IoT Core. For more information, see AWS IoT Core message broker service quotas in the AWS General Reference.