Installer arguments - 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 (PDF).

Installer arguments

The Amazon IoT Greengrass Core software includes an installer that sets up the software and provisions the required Amazon resources for the Greengrass core device to run. The installer includes the following arguments that you can specify to configure the installation:

-h, --help

(Optional) Show the installer's help information.

--version

(Optional) Show the version of the Amazon IoT Greengrass Core software.

-Droot

(Optional) The path to the folder to use as the root for the Amazon IoT Greengrass Core software.

Note

This argument sets a JVM property, so you must specify it before -jar when you run the installer. For example, specify java -Droot="/greengrass/v2" -jar /path/to/Greengrass.jar.

Default:

  • Linux: ~/.greengrass

  • Windows: %USERPROFILE%/.greengrass

-ar, --aws-region

The Amazon Web Services Region that the Amazon IoT Greengrass Core software uses to retrieve or create its required Amazon resources.

-p, --provision

(Optional) You can register this device as an Amazon IoT thing and provision the Amazon resources that the core device requires. If you specify true, the Amazon IoT Greengrass Core software provisions an Amazon IoT thing, (optional) an Amazon IoT thing group, an IAM role, and an Amazon IoT role alias.

Default: false

-tn, --thing-name

(Optional) The name of the Amazon IoT thing that you register as this core device. If the thing with the name doesn't exist in your Amazon Web Services account, the Amazon IoT Greengrass Core software creates it.

Note

The thing name can't contain colon (:) characters.

You must specify --provision true to apply this argument.

Default: GreengrassV2IotThing_ plus a random UUID.

-tgn, --thing-group-name

(Optional) The name of the Amazon IoT thing group where you add this core device's Amazon IoT thing. If a deployment targets this thing group, this core device receives that deployment when it connects to Amazon IoT Greengrass. If the thing group with this name doesn't exist in your Amazon Web Services account, the Amazon IoT Greengrass Core software creates it.

Note

The thing group name can't contain colon (:) characters.

You must specify --provision true to apply this argument.

-tpn, --thing-policy-name

This feature is available for v2.4.0 and later of the Greengrass nucleus component.

(Optional) The name of the Amazon IoT policy to attach to this core device's Amazon IoT thing certificate. If the Amazon IoT policy with this name doesn't exist in your Amazon Web Services account, the Amazon IoT Greengrass Core software creates it.

The Amazon IoT Greengrass Core software creates a permissive Amazon IoT policy by default. You can scope down this policy, or create a custom policy where you restrict permissions for your use case. For more information, see Minimal Amazon IoT policy for Amazon IoT Greengrass V2 core devices.

You must specify --provision true to apply this argument.

Default: GreengrassV2IoTThingPolicy

-trn, --tes-role-name

(Optional) The name of the IAM role to use to acquire Amazon credentials that let the core device interact with Amazon services. If the role with this name doesn't exist in your Amazon Web Services account, the Amazon IoT Greengrass Core software creates it with the GreengrassV2TokenExchangeRoleAccess policy. This role doesn't have access to your S3 buckets where you host component artifacts. So, you must add permissions to your artifacts' S3 buckets and objects when you create a component. For more information, see Authorize core devices to interact with Amazon services.

You must specify --provision true to apply this argument.

Default: GreengrassV2TokenExchangeRole

-tra, --tes-role-alias-name

(Optional) The name of the Amazon IoT role alias that points to the IAM role that provides Amazon credentials for this core device. If the role alias with this name doesn't exist in your Amazon Web Services account, the Amazon IoT Greengrass Core software creates it and points it to the IAM role that you specify.

You must specify --provision true to apply this argument.

Default: GreengrassV2TokenExchangeRoleAlias

-ss, --setup-system-service

(Optional) You can set up the Amazon IoT Greengrass Core software as a system service that runs when this device boots. The system service name is greengrass. For more information, see Configure the Greengrass nucleus as a system service.

On Linux operating systems, this argument requires that the systemd init system is available on the device.

Important

On Windows core devices, you must set up the Amazon IoT Greengrass Core software as a system service.

Default: false

-u, --component-default-user

The name or ID of the user that the Amazon IoT Greengrass Core software uses to run components. For example, you can specify ggc_user. This value is required when you run the installer on Windows operating systems.

On Linux operating systems, you can also optionally specify the group. Specify the user and group separated by a colon. For example, ggc_user:ggc_group.

The following additional considerations apply for Linux operating systems:

  • If you run as root, the default component user is the user that is defined in the configuration file. If the configuration file doesn't define a user, this defaults to ggc_user:ggc_group. If ggc_user or ggc_group don't exist, the software creates them.

  • If you run as a non-root user, the Amazon IoT Greengrass Core software uses that user to run components.

  • If you don't specify a group, the Amazon IoT Greengrass Core software uses the primary group of the system user.

For more information, see Configure the user that runs components.

-d, --deploy-dev-tools

(Optional) You can download and deploy the Greengrass CLI component to this core device. You can use this tool to develop and debug components on this core device.

Important

We recommend that you use this component in only development environments, not production environments. This component provides access to information and operations that you typically won't need in a production environment. Follow the principle of least privilege by deploying this component to only core devices where you need it.

You must specify --provision true to apply this argument.

Default: false

-init, --init-config

(Optional) The path to the configuration file to use to install the Amazon IoT Greengrass Core software. You can use this option to set up new core devices with a specific nucleus configuration, for example.

Important

The configuration file that you specify replaces the existing configuration file on the core device. This erases the existing configuration, which includes the components and component configurations on the core device.

-tp, --trusted-plugin

(Optional) The path to a JAR file to load as a trusted plugin. Use this option to provide provisioning plugin JAR files, such as to install with fleet provisioning or custom provisioning, or to install with the private key and certificate in a hardware security module.

-s, --start

(Optional) You can start the Amazon IoT Greengrass Core software after it installs and, optionally, provisions resources.

Default: true