To create an IoTC package, a specification file (YML) is required. The .yml file describes the content of the package and its associated metadata. You must create a .yml file before creating an IoTC package.
The package-cli.zip archive contains a example-iotc-package folder. Review the contents in this folder before creating the IoTC package.
package: manifest: headlessExecution: true lifecycle: - phase: verify action: <parent directories of build machine>/example-iotc-package/package-source/verify.sh - phase: execute action: <parent directories of build machine>/example-iotc-package/package-source/execute.sh # This phase's action matches the install path of the validate.sh # attachment, so no warning will be issued. - phase: validate action: <parent directories of build machine>/example-iotc-package/package-source/validate_package.sh # This phase's action points to an attachment that doesn't match # any install path, even though there is an attachment named activate.sh - phase: activate action: activate.sh - phase: reset action: <parent directories of gateway>/reset.sh attachments: - path: <parent directories of build machine>/example-iotc-package/package-source/test_file.txt - path: <parent directories of build machine>/example-iotc-package/package-source/verify.sh - path: <parent directories of build machine>/example-iotc-package/package-source/execute.sh - path: <parent directories of build machine>/example-iotc-package/package-source/validate.sh # This will install the validate.sh attachment # in the same directories but named validate_package.sh installPath: <parent directories of build machine>/example-iotc-package/package-source/validate_package.sh - path: <parent directories of build machine>/example-iotc-package/package-source/activate.sh - path: <parent directories of build machine>/example-iotc-package/package-source/reset.sh # You can specify a completely different directory # for attachment installation installPath: <parent directories of gateway>/reset.sh name: hello_iotcp # This is one of the many ways you can create a multiline string in yaml description: "A test IoT Center package with\n a multiline description." version: 1.1.0 # Architecture will be autofilled. architecture: os: linuxIn this example:
attachmentssection lists the files to be included in the package:
path- The path on the disk where the file to be included in the package is located.
installPath- The path on the gateway where the attachments are installed.Note:
installPathis not specified, the
pathvalue is used.
- If any of the directories specified in the
installPathdo not exist, they are created on the gateway if the
iotc-userhas the required permissions.
manifest section describes the package lifecycle and execution. It allows custom actions to be associated with lifecycle events.
- Controls the automatic transition of each lifecycle phase, without any interaction. By default, the value is
headlessExecutionis set to true and the IoTC Agent is configured with
manifestExecution = ENABLED, then the campaign runs automatically without any interaction.
headlessExecutionis set to false and the IoTC Agent is configured with
manifestExecution = ENABLED, then the campaign scheduling depends on an external input such as
DefaultClientor SDK client that must be registered with the IoTC Agent. The executable specified for a particular phase is run by the IoTC Agent at each lifecycle phase.
- If the IoTC Agent is configured with
manifestExecution = DISABLED, then the
headlessExecutionproperty and the executable steps are ignored. Here, all the associated executables are disabled and an SDK client must be configured to run the campaign.
action- An executable file that performs the required tasks for the current phase. For example, the executable file performs tasks such as verifying the downloaded content, setting up the environment, running the installer, and validating whether the installation is successful. The executable file is run in an isolated shell that has the environmental variable
DATADIRset to the path of the directory that contains the extracted package files. If relative paths are used,
DATADIRis set to access the files. For example, the path to access the update_data.tar.gz file is:
All the files from the package with relative paths are deployed in a unique directory at the default path that is configured in the IoTC Agent. The default path can be found in the iotc-agent configuration file, at agent host: /opt/vmware/iotc-agent/conf/iotc-agent.cfg.
agentDataDirPath = /opt/vmware/iotc-agent/data
- Ensure that you provide appropriate access and execution rights to the files, if needed. You can provide permissions through the executables for the lifecycle phases.
- You can specify a relative or an absolute install path for the attachments. If you do not specify the install path, the Package Management CLI tool creates an install path for each attachment.
lifecycle section defines the different lifecycle phases and the corresponding action to take for each phase. For the IoTC Agent to locate an
action executable after the payload is extracted, and to run the executable, the
action path must match the
installPath in the
attachments section. Or, the
action path must point to an existing executable on the gateway. The specification file also specifies the external executables to run at each lifecycle phase.
You can attach executables to all lifecycle phases except the
ENTRYPOINT phase. The executable for the
ENTRYPOINT phase must be present on the Gateway's file system and ready to run.
actionfield, then no action is performed and the phase is considered to pass successfully and the lifecycle moves to the next phase. For example, if you do not provide a verify.sh executable in the VERIFY phase, the package runs without verification (other than the default verification steps provided in the packaging format, such as checksum and RPM signatures), and moves to the VALIDATE state. This process continues until the package moves to the ACTIVATE phase. The phases ACTIVATE and RESET are mutually exclusive. The update is either activated or reset depending on the VALIDATE phase result.
- For all the executables that are attached for the
actionfield, the IoTC Agent sets the execute permission to
(700 / -rwx------)for the
iotc userby default.
- If there are other executables listed in packages/files/scripts beside the executables that are specified in the
actionfield, the author of the executables must manage the required permissions.
ossections are strings that describe the operating system and architecture that the package is built for. If the
ossections are not present or have empty values, the Package Management CLI tool detects the values. These values are supplied to the Package Management CLI tool when building the tool itself. The Package Management CLI tool is available in the following variants. These variants are available in a downloadable file within the package-cli.zip file:
OS = linux, Architecture = amd64
OS = darwin, Architecture = 386
OS = windows, Architecture = amd64
OS = windows, Architecture = 386
noosif it is unable to detect an operating system. Similarly, the Package Management CLI tool defaults to
noarchif it is unable to detect a system architecture.