TorizonCore Builder - 3.0.0 and Later

Introduction

TorizonCore Builder is a tool that enables customizations such as including a splash screen, an overlay, preinstalled containers, capturing device configurations, and more, on TorizonCore in an easy way. The end result is a custom TorizonCore image prepared for production programming. To learn more about the tool and how to get started, please refer to TorizonCore Builder Tool page.

This Commands Manual is intended for those who are already familiar with TorizonCore Builder and have a use case that is not covered in the Torizoncore Builder - Getting Started article, want to use TorizonCore Builder in a particular way, or are looking for more details about a specific command. This article contains a detailed explanation of all TorizonCore Builder commands as well as examples of how to use them.

Requirements

• A Toradex SoM with Torizon installed
• Having read the Torizoncore Builder - Getting Started article

TorizonCore Builder and OSTree

TorizonCore Builder interacts with the OSTree library to capture/apply changes made on a filesystem. We develop TorizonCore Builder in a way that OSTree is abstracted as much as possible for our customers.

OSTree is a library, which official name is libostree, which handles updates for the entire filesystem tree (the whole Linux root filesystem). An essential aspect of OSTree is that it uses a “git-like” model for committing and downloading bootable filesystem trees. The library is a key technology used by Torizon Updates.

The torizoncore-builder command

Note: TorizonCore Builder tool can work either by providing the working directory (capable of carrying Linux filesystem metadata) or Docker volumes for intermediate data storage. So all commands are explained with both approaches.

The usage of the torizoncore-builder command (or, more precisely, alias) can be shown by its --help switch:

Usage

$ torizoncore-builder --help
usage: torizoncore-builder [-h] [--verbose] [--log-level LOG_LEVEL] [--log-file LOG_FILE] [-v] 
                           {build,bundle,combine,deploy,dt,dto,images,isolate,kernel,ostree,platform,push,splash,union} ...

TorizonCore Builder is an utility that allows to create customized TorizonCore OSTree commits and Toradex Easy Installer
images without rebuilding the complete operating system.

optional arguments:
  -h, --help            show this help message and exit
  --verbose             show more output
  --log-level LOG_LEVEL
                        set global log level (debug, info, warning, error, critical)
  --log-file LOG_FILE   write logs to a file instead of console
  -v, --version         show program's version number and exit

Commands:
  {build,bundle,combine,deploy,dt,dto,images,isolate,kernel,ostree,platform,push,splash,union}
    build               Customize a Toradex Easy Installer image based on settings specified via a configuration file.
    bundle              Create container bundle from a Docker Compose file. Can be used to combine with a TorizonCore
                        base image.
    combine             Combines a container bundle with a specified Toradex Easy Installer image.
    deploy              Deploy the current image as a Toradex Easy Installer image.
    dt                  Manage device trees
    dto                 Manage device tree overlays
    images              Manage Toradex Easy Installer Images.
    isolate             capture /etc changes.
    kernel              Manage and modify TorizonCore Linux Kernel.
    ostree              OSTree operational commands
    platform            Execute operations that interact with the Torizon Platform Services (app.torizon.io) or a
                        compatible server
    push                Push artifact to OTA server as a new update package.
    splash              change splash screen
    union               Create a commit out of isolated changes for unpacked Toradex Easy Installer Image

Learn more on https://developer.toradex.com/knowledge-base/torizoncore-builder-tool

The various arguments listed are common to all commands. For example, one could enable the debug messages during the dt status command by doing:

$ torizoncore-builder --log-level debug dt status

In the following items, we describe the commands offered by the tool (in alphabetical order).

The Build Command

build provides full customization of an image as a single step based on a configuration file. Please refer to the TorizonCore Builder Tool “build” command article for a few examples and a detailed explanation of the command. This is the command you should use to prepare images for production programming and provisioning multiple devices

Usage

$ torizoncore-builder build --help
usage: torizoncore-builder build [-h] [--create-template] [--file CONFIG] [--force]
                                 [--set ASSIGNMENT] [--no-subst]

optional arguments:
  -h, --help         show this help message and exit
  --create-template  Request that a template file be generated with the name defined by --file;
                     dump to standard output if file name is set to '-'.
  --file CONFIG      Specify location of the build configuration file (default: tcbuild.yaml).
  --force            Force program output (remove output directory before starting the build
                     process).
  --set ASSIGNMENT   Assign values to variables (e.g. VER="1.2.3"). This can be used multiple
                     times.
  --no-subst         Disable the variable substitution feature.

The Bundle Command

This creates a tar archive of the container images referenced by the provided Docker Compose file and stores that archive in a bundle directory (which, by default, is named "bundle", but this can be changed via the --bundle-directory parameter). The bundle directory can later be provided to the combine command to create a Toradex Easy Installer image containing pre-installed container images. The Toradex Easy Installer tool copies containers data to appropriate places in rootfs while flashing the image on the target board.

Usage

$ torizoncore-builder bundle --help
usage: torizoncore-builder bundle [-h] [--bundle-directory BUNDLE_DIRECTORY] [--force]
                                  [--platform PLATFORM] [--login USERNAME PASSWORD]
                                  [--login-to REGISTRY USERNAME PASSWORD]
                                  [--dind-param DIND_PARAM]
                                  [compose_file]

positional arguments:
  compose_file          Compose file to be processed (REQUIRED); commonly named 'docker-
                        compose.yml'.

optional arguments:
  -h, --help            show this help message and exit
  --bundle-directory BUNDLE_DIRECTORY
                        Container bundle directory
  --force               Force program output (remove output directory before starting the bundle
                        generation process).
  --platform PLATFORM   Default platform for fetching container images when multi-platform images
                        are specified in the compose file (e.g. linux/arm/v7 or linux/arm64).
  --login USERNAME PASSWORD
                        Request that the tool logs in to the default [Docker Hub] registry using
                        specified USERNAME and PASSWORD.
  --login-to REGISTRY USERNAME PASSWORD
                        Request that the tool logs in to registry REGISTRY using specified
                        USERNAME and PASSWORD (can be employed multiple times).
  --dind-param DIND_PARAM
                        Parameter to forward to the Docker-in-Docker container executed by the
                        tool (can be employed multiple times). The parameter will be processed by
                        the Docker daemon (dockerd) running in the container. Please see Docker
                        documentation for more information.

NOTE: following switches have been removed: --docker-username, --docker-password, --registry,
--host-workdir and --file (-f); please review your command line if using any of them.

Example

In its most basic form the command would be run simply as:

$ torizoncore-builder bundle docker-compose.yml

If the Docker Compose file references multi-platform images, then the --platform parameter would be required such as:

$ torizoncore-builder bundle docker-compose.yml --platform linux/arm/v7

The parameter --dind-param allows you to pass parameters to the Docker-in-Docker (DIND) container instance that torizoncore-builder uses to fetch images. One case where this is useful is when your Docker Compose file references insecure registries, in which case the DIND container needs to be informed about the registries to be accessed insecurely. In this example, registry running on machine with IP address 192.168.0.30, port 5001 is to be accessed in this manner:

$ torizoncore-builder bundle docker-compose.yml --platform linux/arm/v7 --dind-param="--insecure-registry=192.168.0.30:5001"

The Combine Command

combine command is used to create Toradex Easy Installer image of Torizon by combining user-provided Toradex Easy Installer image of Torizon (either base Torizon Image OR output (output image) from deploy command) with bundled Docker container(s) from bundle command.

Usage

$ torizoncore-builder combine --help
usage: torizoncore-builder combine [-h] [--bundle-directory BUNDLE_DIRECTORY] [--image-name IMAGE_NAME]
                                   [--image-description IMAGE_DESCRIPTION] [--image-licence LICENCE_FILE]
                                   [--image-accept-licence | --no-image-accept-licence]
                                   [--image-release-notes RELEASE_NOTES_FILE]
                                   [--image-autoinstall | --no-image-autoinstall]
                                   [--image-autoreboot | --no-image-autoreboot]
                                   IMAGE_DIRECTORY OUTPUT_DIRECTORY

positional arguments:
  IMAGE_DIRECTORY       Path to TorizonCore Toradex Easy Installer source image, which needs to be updated with docker
                        bundle.
  OUTPUT_DIRECTORY      Path to combined TorizonCore Toradex Easy Installer image, which needs to be updated with docker
                        bundle.

optional arguments:
  -h, --help            show this help message and exit
  --bundle-directory BUNDLE_DIRECTORY
                        Container bundle directory
  --image-name IMAGE_NAME
                        Image name to be used in Easy Installer image json
  --image-description IMAGE_DESCRIPTION
                        Image description to be used in Easy Installer image json
  --image-licence LICENCE_FILE
                        Licence file which will be shown on image installation
  --image-accept-licence, --no-image-accept-licence
                        Automatically accept the licence referenced in the image (already present in the input image or
                        being set via --image-licence); Licence should be accepted every time an image is generated
  --image-release-notes RELEASE_NOTES_FILE
                        Release notes file which will be shown on image installation
  --image-autoinstall, --no-image-autoinstall
                        Automatically install image upon detection by Toradex Easy Installer.
  --image-autoreboot, --no-image-autoreboot
                        Enable automatic reboot after image is flashed by Toradex Easy Installer.

NOTE: the switches --image-directory and --output_directory have been removed.

The Deploy Command

deploy takes a branch (containing the commit for changes) from the union command and deploys it to either a Toradex Easy Installer image or a live device (via an SSH connection). When deploying to a Toradex Easy Installer image, the present command is commonly employed together with the commands bundle and combine; the former will download container images and store them into a bundle which can then be combined into a new installer image via the combine command. The bundled application containers can not be deployed using this command when targeting a live device.

Usage

$ torizoncore-builder deploy --help
usage: torizoncore-builder deploy [-h] [--output-directory OUTPUT_DIRECTORY] [--remote-host REMOTE_HOST]
                                  [--remote-username REMOTE_USERNAME] [--remote-password REMOTE_PASSWORD]
                                  [--remote-port REMOTE_PORT] [--mdns-source MDNS_SOURCE] [--reboot]
                                  [--deploy-sysroot-directory DEPLOY_SYSROOT_DIRECTORY] [--image-name IMAGE_NAME]
                                  [--image-description IMAGE_DESCRIPTION] [--image-licence LICENCE_FILE]
                                  [--image-accept-licence | --no-image-accept-licence]
                                  [--image-release-notes RELEASE_NOTES_FILE] [--image-autoinstall | --no-image-autoinstall]
                                  [--image-autoreboot | --no-image-autoreboot]
                                  [REF]

positional arguments:
  REF                   OSTree reference to deploy.

optional arguments:
  -h, --help            show this help message and exit
  --output-directory OUTPUT_DIRECTORY
                        Output path for TorizonCore Toradex Easy Installer image.
  --remote-host REMOTE_HOST
                        Remote host machine to deploy to.
  --remote-username REMOTE_USERNAME
                        Username of remote machine (default value is torizon)
  --remote-password REMOTE_PASSWORD
                        Password of remote machine (default value is torizon)
  --remote-port REMOTE_PORT
                        SSH port (default value is 22)
  --mdns-source MDNS_SOURCE
                        Use the given IP address as mDNS source. This is useful when multiple interfaces are used, and mDNS
                        multicast requests are sent out the wrong network interface.
  --reboot              Reboot machine after deploying
  --deploy-sysroot-directory DEPLOY_SYSROOT_DIRECTORY
                        Work directory to store the intermittent deployment sysroot. NOTE: OSTree need to be able to write
                        extended attributes in this directory. This seems to only reliably work when using a Docker volume!
  --image-name IMAGE_NAME
                        Image name to be used in Easy Installer image json
  --image-description IMAGE_DESCRIPTION
                        Image description to be used in Easy Installer image json
  --image-licence LICENCE_FILE
                        Licence file which will be shown on image installation
  --image-accept-licence, --no-image-accept-licence
                        Automatically accept the licence referenced in the image (already present in the input image or
                        being set via --image-licence); Licence should be accepted every time an image is generated
  --image-release-notes RELEASE_NOTES_FILE
                        Release notes file which will be shown on image installation
  --image-autoinstall, --no-image-autoinstall
                        Automatically install image upon detection by Toradex Easy Installer.
  --image-autoreboot, --no-image-autoreboot
                        Enable automatic reboot after image is flashed by Toradex Easy Installer.

When deploying to a live device, at least switch --remote-host must be passed possibly along with the other --remote-... switches. Switches --image-... are relevant only when deploying to a Toradex Easy Installer image: they set properties inside the image.json file of the generated image.

Example

Deploying to a live device

$ torizoncore-builder deploy my-branch --remote-host 192.168.0.34 --remote-username torizon --remote-password "1234"

Deploying to a Toradex Easy Installer image

$ torizoncore-builder deploy my-branch --output-directory my-custom-image-dir

The Dt (Device Tree) Command

dt has subcommands to build and apply custom device trees to devices. Refer to Device Tree Overlays on Torizon for details on usage.

 $ torizoncore-builder dt --help
usage: torizoncore-builder dt [-h] {status,checkout,apply} ...

Manage application of device trees.

optional arguments:
  -h, --help            show this help message and exit

Commands::
  {status,checkout,apply}
    status              Show the current device tree
    checkout            Checkout the Toradex device tree and overlay repository
    apply               Compile and enable a device tree

dt checkout

The dt checkout is simply a convenience wrapper for retrieving the Toradex device tree and overlays repository at https://github.com/toradex/device-trees. This repository contains sources for common combinations of device trees and overlays compatible with Toradex SOMs and carrier boards. The repository is checked out in subdirectory device-trees in torizoncore-builder's working directory.

Note: The tool will choose which branch to check out based on metadata found on the image currently unpacked in the storage directory; this means this command is supposed to be used after executing images unpack or images download.

Usage

$ torizoncore-builder dt checkout --help
Checkout Toradex device tree and overlays repository

optional arguments:
  -h, --help  show this help message and exit
  --update    Update device-trees repository (if existing)

If the --update switch is passed, the tool will simply perform a git pull inside the device-trees directory if the directory already exists.

dt apply

Compiles a device tree source file and, on success, stores the compiled device tree blob to be deployed as the current device tree of the deployed image (see the union and deploy commands).

A note for advanced users: TorizonCore overrides the default value of the U-Boot environment variable fdtfile in a file named uEnv.txt, which is evaluated during U-Boot runtime. Therefore, if you read the value of fdtfile using a tool like U-Boot fw-utils or directly from the bootloader, you will not be reading the value to which this variable evaluates, instead, you should check the contents of /boot/loader/uEnv.txt.

Usage

$ torizoncore-builder dt apply --help
usage: torizoncore-builder dt apply [-h] [--include-dir DIR] DEVICE_TREE

Compile and enable a device tree

positional arguments:
  DEVICE_TREE        Path to the device tree source file

optional arguments:
  -h, --help         show this help message and exit
  --include-dir DIR  Search directory for include files during device tree compilation.
                     Can be passed multiple times. If absent, defaults to 'device-trees/include'.

Example

$ torizoncore-builder dt apply device-trees/dts-arm64/imx8qxp-colibri-aster.dts
<...>
/tmp/tmpiyorpx7w: Device Tree Blob version 17, size=120412, boot CPU=0, string block size=7360, DT structure block size=112996
Device tree imx8qxp-colibri-aster.dtb successfully applied.

dt status

Shows the current device tree of the image, if any. Note: On some devices, the device tree is selected at boot time according to characteristics of the hardware. In such cases dt status does not show the enabled device tree.

Example

$ torizoncore-builder dt status
Current device tree is: imx8qxp-colibri-aster.dtb

The Dto (Device Tree Overlay) Command

dto has subcommands to build and apply custom overlays to the current device tree. Refer to Device Tree Overlays on Torizon for details on usage.

$ torizoncore-builder dto --help
usage: torizoncore-builder dto [-h] {apply,list,status,remove,deploy} ...

Manage device tree overlays

optional arguments:
  -h, --help            show this help message and exit

Commands:
  {apply,list,status,remove,deploy}
    apply               Apply a device tree overlay
    list                List the device tree overlays compatible with the current device tree
    status              List the applied device tree overlays
    remove              Remove a device tree overlay
    deploy              Deploy a device tree overlay in the device

dto apply

Compiles a device tree overlay source file. On success, test if it's applicable against the current device tree (+ other previously applied overlays). On success, stores the compiled device tree overlay blob to be deployed as part of the set of overlays that are applied to the current device tree of the deployed image during boot.

Usage

$ torizoncore-builder dto apply --help
usage: torizoncore-builder dto apply [-h] [--include-dir DIR] [--device-tree FILE] [--force] OVERLAY

Apply a further overlay to the current device tree.

positional arguments:
  OVERLAY             Path to the overlay source file

optional arguments:
  -h, --help          show this help message and exit
  --include-dir DIR   Search directory for include files during overlay compilation. Can be passed multiple times.
                      If absent, defaults to 'device-trees/include'.
  --device-tree FILE  Test overlay application over this device tree blob instead of the current device tree.
  --force             Apply the overlay even on failure checking it against the current device tree.

Example

$ torizoncore-builder dto apply device-trees/overlays/colibri-imx8x_dsihdmi_overlay.dts
/tmp/tmpfmxpe871: Device Tree Blob version 17, size=2323, boot CPU=0, string block size=275, DT structure block size=1992
Overlay 'device-trees/overlays/colibri-imx8x_dsihdmi_overlay.dts' compiles successfully.
/tmp/tmpp64__jp9: Device Tree Blob version 17, size=121434, boot CPU=0, string block size=7462, DT structure block size=113916
Overlay colibri-imx8x_dsihdmi_overlay.dtbo successfully applied.

dto list

Scan subdirectory device-trees/overlays of TorizonCore Builder's working directory for overlay source files that are declared to be compatible to the current device tree.

Usage

$ torizoncore-builder dto list --help
usage: torizoncore-builder dto list [-h] [--device-tree FILE]

List overlays compatible to the current device tree.

optional arguments:
  -h, --help          show this help message and exit
  --device-tree FILE  Check for overlay compatibility against this device tree blob instead of the current device tree.

Example

 $ torizoncore-builder dto list
Overlays compatible with device tree imx8qxp-colibri-aster.dtb:
- device-trees/overlays/colibri-imx8x_ad7879_overlay.dts
- device-trees/overlays/colibri-imx8x_atmel-mxt_overlay.dts
- device-trees/overlays/colibri-imx8x_dsihdmi_overlay.dts
- device-trees/overlays/colibri-imx8x_parallel-rgb_overlay.dts
- device-trees/overlays/display-dpi-lt170410_overlay.dts

dto status

Shows the applied device tree overlays that will be deployed.

Usage

 $ torizoncore-builder dto status --help
usage: torizoncore-builder dto status [-h]

List the applied overlays.

optional arguments:
  -h, --help  show this help message and exit

Example

$ torizoncore-builder dto status
Enabled overlays over device tree imx8qxp-colibri-aster.dtb:
- colibri-imx8x_dsihdmi_overlay.dtbo
- colibri-imx8x_atmel-mxt_overlay.dtbo

dto remove

Remove a device tree overlay blob from the set of applied overlays.

Usage

$ torizoncore-builder dto remove --help
usage: torizoncore-builder dto remove [-h] [--all] [OVERLAY]

Remove an overlay that is not yet deployed.

positional arguments:
  OVERLAY     Name of the device tree overlay blob

optional arguments:
  -h, --help  show this help message and exit
  --all       Remove all overlays instead.

Example

$ torizoncore-builder dto remove colibri-imx8x_dsihdmi_overlay.dtbo

dto deploy

Deploy a device tree overlay in the device with a single command. This command will download a Toradex Easy Installer image based on the running device, unpack this image, apply the Device Tree overlay, create a union branch, and deploy the image to the device.

Usage

$ torizoncore-builder dto deploy --help
usage: torizoncore-builder dto deploy [-h] --remote-host REMOTE_HOST [--remote-username REMOTE_USERNAME] [--remote-password REMOTE_PASSWORD]
                                      [--remote-port REMOTE_PORT] [--reboot] [--mdns-source MDNS_SOURCE] [--include-dir DIR]
                                      [--force] [--device-tree FILE] [--clear] OVERLAY [OVERLAY ...]

Deploy a device tree overlay in the device

positional arguments:
  OVERLAY               Path to the device tree overlay source file(s)

optional arguments:
  -h, --help            show this help message and exit
  --remote-host REMOTE_HOST
                        Name/IP of remote machine
  --remote-username REMOTE_USERNAME
                        Username of remote machine (default value is torizon)
  --remote-password REMOTE_PASSWORD
                        Password of remote machine (default value is torizon)
  --remote-port REMOTE_PORT
                        SSH port (default value is 22)
  --reboot              Reboot device after deploying device tree overlay(s)
  --mdns-source MDNS_SOURCE
                        Use the given IP address as mDNS source. This is useful when multiple interfaces are used, and mDNS multicast requests are sent out the wrong network interface.
  --include-dir DIR     Search directory for include files during overlay compilation. Can be passed multiple times. If absent, defaults to 'device-trees/include'
  --force               Apply the overlay even on failure checking it against a device tree.
  --device-tree FILE    Test the overlay against an specific device tree.
  --clear               Remove all currently applied device tree overlays.

Example

$ torizoncore-builder dto deploy --remote-host <Hostname/IP address of target board> --remote-username <User on target board> --remote-password <Password of user on target board> --remote-port <ssh port of the remote target machine> --force --reboot device-trees/overlays/display-lt161010_overlay.dts 
Downloading image from: https://artifacts.toradex.com/artifactory/torizoncore-oe-prod-frankfurt/dunfell-5.x.y/release/1/verdin-imx8mm/torizon/torizon-core-docker/oedeploy/torizon-core-docker-verdin-imx8mm-Tezi_5.1.0+build.1.tar

The download may take some time. Please wait...
Download Complete!

Unpacking Toradex Easy Installer image.
Copying Toradex Easy Installer image.
Unpacking TorizonCore Toradex Easy Installer image.
Importing OSTree revision 8c514a595469283bb69603f2fa32395b5dbbc3d80a8f9d824dc661f1b68c4d82 from local repository...
0 metadata, 0 content objects imported; 0 bytes content written                                                                                                                                            
Unpacked OSTree from Toradex Easy Installer image:
  Commit checksum: 8c514a595469283bb69603f2fa32395b5dbbc3d80a8f9d824dc661f1b68c4d82
  TorizonCore Version: 5.1.0+build.1
'device-trees' directory already exists
'display-lt161010_overlay.dts' compiles successfully.
warning: --force was used, bypassing checking overlays against the device tree.
Overlay display-lt161010_overlay.dtbo successfully applied.
Commit 40aec4200054c9865aa6e0b13acdeb9ed63ac5a91e9276800e4a22850f42d84b has been generated for changes and ready to be deployed.
Pulling OSTree with ref dto_deploy (checksum 40aec4200054c9865aa6e0b13acdeb9ed63ac5a91e9276800e4a22850f42d84b) from local archive repository...
Starting http server to serve OSTree.
Starting OSTree pull on the device...
Deploying new OSTree on the device...
Deploying successfully finished.
Device reboot initiated...

The Images Command

images gets the base Toradex Easy Installer image of Torizon and unpacks the rootfs (OSTree filesystem) to a Docker volume. This command has the following subcommands and options:

$ torizoncore-builder images --help
usage: torizoncore-builder images [-h] [--remove-storage] {download,provision,serve,unpack} ...

optional arguments:
  -h, --help            show this help message and exit
  --remove-storage      Automatically clear storage prior to unpacking a new Easy Installer image.

Commands:
  {download,provision,serve,unpack}
    download            Download image from Toradex Artifactory and unpack it.
    provision           Generate a Toradex Easy Installer image with provisioning data for secure updates.
    serve               Serve TorizonCore Toradex Easy Installer images via HTTP.
    unpack              Unpack a specified Toradex Easy Installer image so it can be modified with the union subcommand.

images download

Warning: Pre-production level Easy Installer images (monthly, nightly) are pruned from the Toradex Artifacts server on a regular basis. This may result in download not being able to locate the image.

Connects to a remote Torizon device and via the version information determines the source Easy Installer image. The deduced image is then downloaded from the Toradex Artifacts repository into the user's working directory. Finally, the command will unpack the rootfs (OSTree filesystem) of the downloaded to a Docker volume.

Usage

$ torizoncore-builder images download --remote-host <hostname/IP address of target board> --remote-username <username on target board> --remote-password <password of user on target board> --remote-port <ssh port of the remote target machine>

Arguments

--remote-host: IP or hostname of the target board

--remote-username: username of the target board, to be used for creating ssh session.

--remote-password: user password of the target board, to be used for creating ssh session

--remote-port: ssh port of the target board, to be used for creating ssh session

Example

With docker volume

$ torizoncore-builder images download --remote-host <hostname/IP address of target board> --remote-username <username on target board> --remote-password <password of user on target board> --remote-port <ssh port of the target board>

Without docker volume

Additional argument --storage-directory specified with alias torizoncore-builder, sets the path (capable of handling Linux filesystem metadata) to be used to store intermediate data. It will be used to store unpacked OSTree rootfs as a result of this command.

$ torizoncore-builder --storage-directory <path to user storage directory> images download --remote-host <hostname/IP address of target board> --remote-username <username on target board> --remote-password <password of user on target board> --remote-port <ssh port of the target board>

images provision

Generate a Toradex Easy Installer image with provisioning data so that when deployed during production programming, the programmed devices can be configured for using secure updates.

When generating images that will be deployed as updates, you should not generate the new images with the provisioning data. You just have to maintain the configuration changes in case of using offline updates.

There are two types of provisioning at the moment:

• offline: a device where the resulting image is installed will be ready to accept offline-updates produced by the Torizon Platform account from where the "shared data" came from;
• online: a device where the resulting image is installed will contain information allowing it to automatically register itself to the Torizon Platform (using credentials contained in the "online data" coming from a certain Torizon Platform account); besides it will also be able to accept offline-updates.

Usage

$ torizoncore-builder images provision -h
usage: torizoncore-builder images provision [-h] --mode {offline,online} [--force]
                                            [--shared-data SHARED_DATA_FILE]
                                            [--online-data ONLINE_DATA]
                                            INPUT_DIRECTORY OUTPUT_DIRECTORY

positional arguments:
  INPUT_DIRECTORY       Path to input TorizonCore Toradex Easy Installer image.
  OUTPUT_DIRECTORY      Path to output TorizonCore Toradex Easy Installer image, which will hold
                        provisioning data.

optional arguments:
  -h, --help            show this help message and exit
  --mode {offline,online}
                        Select type of provisioning; online mode encompasses offline mode.
  --force               Force program output (remove output directory before starting process).
  --shared-data SHARED_DATA_FILE
                        Archive containing shared provisioning data.
  --online-data ONLINE_DATA
                        String containing sensitive data required for online provisioning
                        (base64-encoded).

images serve

Serve (via HTTP) TorizonCore images from a directory so those images can be installed in a Toradex device using Toradex Easy Installer.

Attention: The torizoncore-builder image serve command only works for TorizonCore Builder running on Linux. There are some known issues when running it on Windows that will be addressed in future releases.

Usage

$ torizoncore-builder images serve <Easy Installer images directory>

Example

Warning: The following example assumes that the customer has already built or downloaded a TorizonCore image and that it is stored inside an images/apalis-imx6-img directory.

Create a JSON file, called images_list.json, that defines images which should be shown as installation options to Toradex Easy Installer. The images_list.json file must be stored inside the images directory and should have the following format:

 ./images/images_list.json
{
    "config_format": 1,
    "images": [
        "apalis-imx6-img/image.json"
    ]
}

An example of the layout of the image directory would be:

$ tree images/
images/
├── apalis-imx6-img
│   ├── image.json
│   ├── LA_OPT_NXP_SW.html
│   ├── marketing.tar
│   ├── prepare.sh
│   ├── SPL
│   ├── toradexlinux.png
│   ├── torizon-core-docker-apalis-imx6.ota.tar.zst
│   ├── u-boot.img
│   ├── u-boot-initial-env-spl
│   └── wrapup.sh
└── image_list.json

1 directory, 11 files

With this directory structure in place, execute:

$ torizoncore-builder images serve images/

From this moment on, TorizonCore Builder will serve images to any board with Toradex Easy Installer executing on the local network.

Note: It is possible to provide more than one image at the same time. In order to do this, you should list all the images directories inside the image_list.json file. For example:

 ./images/images_list.json
{
    "config_format": 1,
    "images": [
        "apalis-imx6-img1/image.json",
        "apalis-imx6-img2/image.json",
        "apalis-imx6-img3/image.json",
    ]
}

images unpack

Takes a user-provided Toradex Easy Installer image and unpacks the rootfs (OSTree filesystem) to a Docker volume. It is not necessary to use this command if you have previously used images download.

Usage

$ torizoncore-builder images unpack <base Toradex Easy Installer image of Torizon>

Example

Note: If there is already an unpacked OSTree filesystem, the user is prompted to delete it because currently, a single OSTree filesystem can be handled. This prompt can be automated via the --remove-storage argument of the images command.

With docker volume

$ torizoncore-builder images unpack <path to base Toradex Easy Installer image of Torizon in the working directory>

Without Docker Volume

Additional argument --storage-directory specified with alias torizoncore-builder, sets the path(capable of handling Linux filesystem metadata) to be used to store intermediate data. It will be used to store unpacked OSTree rootfs as a result of this command.

$ torizoncore-builder --storage-directory <path to user storage directory> images unpack <path to base Toradex Easy Installer image of Torizon in working directory>

The Isolate Command

isolate get configuration changes(modifications/addition/deletion/files and directories permissions and ownership) from the target board. It creates an ssh session with the target board to get changes and store them within Docker volume on the host.

isolate command gets the configuration (/etc) changes (modifications, additions, deletions, files and directories permissions and ownership) from the user target module. It ignores the following files/directories for any change.

'gshadow', 'machine-id', 'group', 'shadow', 'systemd/system/sysinit.target.wants/run-postinsts.service',
'ostree/remotes.d/toradex-nightly.conf', 'docker/key.json', '.updated', '.pwd.lock', 'group-',
'gshadow-', 'hostname', 'ssh/ssh_host_rsa_key', 'ssh/ssh_host_rsa_key.pub', 'ssh/ssh_host_ecdsa_key',
'ssh/ssh_host_ecdsa_key.pub','ssh/ssh_host_ed25519_key','ssh/ssh_host_ed25519_key.pub',
'ipk-postinsts', 'fw_env.conf'

Files and directories permissions and ownership will be saved in the /etc/.tcattr metadata file together with all other isolated files.

Usage

$ torizoncore-builder isolate --help
usage: torizoncore-builder isolate [-h] [--changes-directory CHANGES_DIR] [--force] --remote-host REMOTE_HOST 
                                   [--remote-username REMOTE_USERNAME] [--remote-password REMOTE_PASSWORD]
                                   [--remote-port REMOTE_PORT] [--mdns-source MDNS_SOURCE]

optional arguments:
  -h, --help            show this help message and exit
  --changes-directory CHANGES_DIR
                        Directory to save the isolated changes from the device. Must be a file system capable of carrying Linux file system metadata (Unix file permissions and xattr). If not passed,
                        defaults to a directory in the storage volume.
  --force               Force removal of storage changes directory
  --remote-host REMOTE_HOST
                        name/IP of remote machine
  --remote-username REMOTE_USERNAME
                        Username of remote machine (default value is torizon)
  --remote-password REMOTE_PASSWORD
                        Password of remote machine (default value is torizon)
  --remote-port REMOTE_PORT
                        SSH port (default value is 22)
  --mdns-source MDNS_SOURCE
                        Use the given IP address as mDNS source. This is useful when multiple interfaces are used, and mDNS multicast requests are sent out the wrong network interface.

Example

You can find the example and detailed instructions on how to use isolate at the Capturing Changes in the Configuration of a Board on TorizonCore article.

The Kernel Command

kernel is used to make modifications related to the Linux kernel of TorizonCore.

$ torizoncore-builder kernel --help
usage: torizoncore-builder kernel [-h] {build_module,set_custom_args,get_custom_args,clear_custom_args} ...

optional arguments:
  -h, --help            show this help message and exit

Commands:
  {build_module,set_custom_args,get_custom_args,clear_custom_args}
    build_module        Build the kernel module at the provided source directory.
    set_custom_args     Set the TorizonCore kernel arguments.
    get_custom_args     Get the TorizonCore kernel arguments.
    clear_custom_args   Clear the TorizonCore kernel arguments.

kernel buildmodule

Build a kernel module from sources and stores the binary to be deployed to a TorizonCore system. Can also configure built kernel modules to be loaded on system boot.

Usage

$ torizoncore-builder kernel build_module --help
usage: torizoncore-builder kernel build_module [-h] [--autoload] [SRC_DIR]

positional arguments:
  SRC_DIR     Path to directory with kernel module source code.

optional arguments:
  -h, --help  show this help message and exit
  --autoload  Configure kernel module to be loaded on startup.

Arguments

--autoload: Configures all built kernel modules to be loaded on system boot.

Example

You can find an example and detailed instructions on how to use kernel build_module at the Building External Kernel Modules With Torizon article.

kernel setcustomargs

Define custom arguments to be passed to the kernel of the image to be deployed. Later executions of this command will completely override the set of arguments previously defined. At runtime, the custom arguments are appended to the default kernel arguments defined in the image. This command is a wrapper around dto apply and, as such, it applies a device-tree overlay (named custom-kargs_overlay.dtbo) to the image.

Refer to Customizing Kernel Arguments in Torizon for details on usage.

Warning: Since the custom kernel arguments are stored in an overlay, the command dto status will display that overlay as part of its output. Also removing the corresponding overlay with dto remove will clear any custom kernel arguments (though the recommended way of doing that is via kernel clear_custom_args).

Usage

$ torizoncore-builder kernel set_custom_args --help
usage: torizoncore-builder kernel set_custom_args [-h] KERNEL_ARGS [KERNEL_ARGS ...]

positional arguments:
  KERNEL_ARGS  Kernel arguments to be added.

optional arguments:
  -h, --help   show this help message and exit

Example

$ torizoncore-builder kernel set_custom_args "param1=val1" "param2=val2"
'custom-kargs_overlay.dts' compiles successfully.
Overlay custom-kargs_overlay.dtbo successfully applied.
Kernel custom arguments successfully configured with "param1=val1 param2=val2".

kernel getcustomargs

Get the custom arguments to be passed to the TorizonCore kernel of the image to be deployed (as previously set by kernel set_custom_args).

Usage

$ torizoncore-builder kernel get_custom_args --help
usage: torizoncore-builder kernel get_custom_args [-h]

optional arguments:
  -h, --help  show this help message and exit

Example

$ torizoncore-builder kernel get_custom_args
Currently configured custom kernel arguments: "param1=val1 param2=val2".

kernel clearcustomargs

Clear the custom arguments to be passed to the kernel (previously set by kernel set_custom_args). This will basically remove the overlay custom-kargs_overlay.dtbo from the image to be deployed.

Usage

$ torizoncore-builder kernel clear_custom_args --help
usage: torizoncore-builder kernel clear_custom_args [-h]

optional arguments:
  -h, --help  show this help message and exit

Example

$ torizoncore-builder kernel clear_custom_args
Custom kernel arguments successfully cleared.

The OSTree Command

OSTree related operations.

Usage

$ torizoncore-builder ostree --help
usage: torizoncore-builder ostree [-h] {serve} ...

optional arguments:
  -h, --help  show this help message and exit

Commands:
  {serve}
    serve     Serve OSTree on the local network using http

ostree serve

Serve an OSTree repository via HTTP.

NOTE: Windows (WSL2) users will need to pass extra parameters to the environment setup script before using this command; this is required so that the port to which the server will listen (8080) is published by the container running the tool. Example (Windows only):

$ tcb-env-setup.sh -- -p 8080:8080

The above note does not apply to users of Linux where the setup script should be executed as usual.

Usage

$ torizoncore-builder ostree serve --help
usage: torizoncore-builder ostree serve [-h] [--ostree-repo-directory OSTREE_REPO_DIRECTORY]

optional arguments:
  -h, --help            show this help message and exit
  --ostree-repo-directory OSTREE_REPO_DIRECTORY
                        Path to the OSTree repository to serve (defaults to internal archive repository)

The Platform Command

The platform executes operations that will interact with Torizon Platform Services (app.torizon.io) or a compatible server. The command has the following subcommands and options:

$ torizoncore-builder platform --help
usage: torizoncore-builder platform [-h] {lockbox,provisioning-data,push} ...

optional arguments:
  -h, --help            show this help message and exit

Commands:
  {lockbox,provisioning-data,push}
    lockbox             Generate a Lockbox for secure offline updates, in a format ready to copy
                        to an SD Card or USB Stick.
    provisioning-data   Fetch provisioning data for secure updates.
    push                Push artifact to OTA server as a new update package.

platform lockbox

Generates a Lockbox by fetching the metadata from Torizon Platform, creating a unique secure image for offline updates in a format ready to copy to an SD Card or USB Stick.

Usage

$ torizoncore-builder platform lockbox --help
usage: torizoncore-builder platform lockbox [-h] --credentials CREDENTIALS [--force] [--platform PLATFORM]
                                            [--login USERNAME PASSWORD] [--output-directory OUTPUT_DIRECTORY] LOCKBOX_NAME

positional arguments:
  LOCKBOX_NAME          Name of the Lockbox (as defined at the OTA server)

optional arguments:
  -h, --help            show this help message and exit
  --credentials CREDENTIALS
                        Relative path to credentials.zip.
  --force               Force program output (remove output directory before generating the Lockbox image).
  --platform PLATFORM   Define platform to select when not specified in the compose file (can be specified multiple
                        times; default: linux/arm/v7, linux/arm64).
  --login USERNAME PASSWORD
                        Request that the tool logs in to the default [Docker Hub] registry using specified USERNAME
                        and PASSWORD.
  --output-directory OUTPUT_DIRECTORY
                        Relative path to the output directory (default: update/). If parent directories are passed
                        such as in a/b/update/, they will be automatically created.

After the Lockbox is generated, the output directory should be copied (and possibly renamed) to the removable media
used for the offline updates; the name of the directory in the media should be in accordance with the update client
(aktualizr) configuration.

Example

Creating a Lockbox

After defining a Lockbox on the Torizon Platform, run the command below:

$ torizoncore-builder platform lockbox my_lockbox_name --credentials credentials.zip

platform provisioning-data

Fetch provisioning data for secure updates.

Usage

$ torizoncore-builder platform provisioning-data --help
usage: torizoncore-builder platform provisioning-data [-h] --credentials CREDENTIALS
                                                      [--shared-data SHARED_DATA_FILE]
                                                      [--online-data CLIENT_NAME] [--force]

optional arguments:
  -h, --help            show this help message and exit
  --credentials CREDENTIALS
                        Relative path to credentials.zip.
  --shared-data SHARED_DATA_FILE
                        Destination archive for shared provisioning data; currently, this must
                        have the ".tar.gz" extension.
  --online-data CLIENT_NAME
                        Client name for which online provisioning data will be obtained and
                        displayed; pass a value of DEFAULT (all capitals) to get the default
                        provisioning data from your credentials file.
  --force               Overwrite output file if it already exists.

Switch --shared-data is normally employed with "offline" provisioning mode while with "online"
provisioning both --shared-data and --online-data switches are commonly used together.

Example

Offline provisioning

To get the data required for offline secure updates provisioning one can execute:

$ torizoncore-builder platform provisioning-data \
    --credentials credentials.zip \
    --shared-data shared-data.tar.gz

The tool will generate file shared-data.tar.gz which can be used with the build command or with the images provision command.

Online provisioning

To get the data required for online secure updates provisioning one can execute:

$ torizoncore-builder platform provisioning-data \
    --credentials credentials.zip \
    --shared-data shared-data.tar.gz --online-data DEFAULT

In this case, the tool will generate file shared-data.tar.gz and display a base64 encoded string that can be used with the build command or with the images provision command.

Note: At the moment, the only supported value for the argument to the switch --online-data is the string DEFAULT; in the future the argument will represent the name of an API client as defined in the Platform web UI.

platform push

The platform push command will take an OSTree reference (commit or branch) or a docker-compose file and upload it to the OTA server using the specified account credentials. Additionally, it will add the uploaded file to the list of packages available at the server-side so that the package could be assigned for OTA deployment to devices.

Usage

$ torizoncore-builder platform push --help
usage: torizoncore-builder platform push [-h] [--credentials CREDENTIALS] [--repo OSTREE] [--hardwareid HARDWAREIDS]
                                         [--package-name TARGET] [--package-version VERSION] [--canonicalize | --no-canonicalize]
                                         [--canonicalize-only] [--force] [--verbose]
                                         REF

positional arguments:
  REF                   OSTree reference or docker-compose file to push to Torizon OTA.

optional arguments:
  -h, --help            show this help message and exit
  --credentials CREDENTIALS
                        Relative path to credentials.zip.
  --repo OSTREE         OSTree repository to push from.
  --hardwareid HARDWAREIDS
                        Hardware ID to use when pushing an OSTree package (can be specified multiple times).
                        Will allow this package to be compatible with devices of the same Hardware ID.
  --package-name TARGET
                        Package name for docker-compose file (default: name of file being pushed to OTA) or OSTree
                        reference (default: same as REF).
  --package-version VERSION
                        Package version for docker-compose file (default: current date following the 'yyyy-mm-dd'
                        format) or OSTree reference (default: OSTree subject).
  --canonicalize, --no-canonicalize
                        Generates a canonicalized version of the docker-compose file, changing its extension to
                        '.lock.yml' or '.lock.yaml' and pushing it to Torizon OTA; The package name is the name of
                        the generated file if no package name is provided.
  --canonicalize-only   Canonicalize the docker-compose.yml file but do not send it to OTA server.
  --force               Force removal of the canonicalized file if it already exists.
  --verbose             Show more output

Note: for a docker-compose file to be suitable for use with offline-updates it must be in canonical form; this can be achieved 
by passing the '--canonicalize' switch to the program in which case the file will be translated into canonical form before being
uploaded to the server.

Example

You can find the example and detailed instructions on how to use platform push at Signing and pushing the image to Torizon OTA.

The Push Command

Warning: The push command is deprecated and will be removed in an upcoming major release of TorizonCore Builder. Please use platform push instead.

The Splash Command

Set a splash screen (image shown during boot) for the image. Refer to Splash Screen on TorizonCore for details.

Usage

$ torizoncore-builder splash --help
usage: torizoncore-builder splash [-h] SPLASH_IMAGE

positional arguments:
  SPLASH_IMAGE  Path and name of splash screen image (REQUIRED).

optional arguments:
  -h, --help    show this help message and exit

NOTE: the switches --image and --work-dir have been removed.

The Union Command

union makes an OSTree branch (containing the commit for changes) for all changes provided by the user to be made in OSTree rootfs of unpacked base Torizon image. It commits changes made by isolate, splash, dt and kernel commands to the OSTree repo i.e., unpacked Toradex Easy Installer image of Torizon.

Note: If the user has used the union command, the deploy command is necessary to deploy the OSTree branch either on the target machine connected via ssh OR onto the OSTree file system (from unpacked Toradex Easy Installer image of Torizon) and to create a new Toradex Easy Installer image of Torizon.

When using the optional --changes-directory parameter, the user has the possibility to set attributes (permissions and ownership) for files and directories that they would like to have set in the OSTree rootfs. That could be made using the .tcattr file.

Usage

usage: torizoncore-builder union [-h] [--changes-directory CHANGES_DIRS]
                                 [--subject SUBJECT] [--body BODY] UNION_BRANCH

positional arguments:
  UNION_BRANCH          Name of branch containing the changes committed to the unpacked repository (REQUIRED).

optional arguments:
  -h, --help            show this help message and exit
  --changes-directory CHANGES_DIRS
                        Path to the directory containing user changes. Can be specified multiple times!
  --subject SUBJECT     OSTree commit subject. Defaults to TorizonCore Builder [timestamp]
  --body BODY           OSTree commit body message

Setting attributes to files and directories using the ".tcattr" file

When using --changes-directory (or --extra-changes-directory in older versions of the tool), you can create a ".tcattr" file which will set the attributes for files and directories in the OSTree filesystem. Basically, you just have to provide the permissions and ownership for files and directories that you want to be set in your final TorizonCore image. The .tcattr file uses the Linux utility getfacl format, so you can learn more about that format by reading the man getfacl.

Example of creating a ".tcattr" file for an additional changes directory

To set attributes for files and directories under /usr/dir1 in your final image or OSTree rootfs of TorizonCore, you should create, in your host machine, the directory ./extra/usr. Inside that directory, you can have whatever files and or directories you like. For each file and directory, you must create entries in the ./extra/.tcattr file with the desired attributes.

For example, imagine that you want the directory usr/dir1 in your ./extra changes directory to have user id 1000, group id 1000 and that only the owner of this directory has execute, read and write permissions. So, you should create an entry in the ./extra/.tcattr file for that directory using the following steps:

$ cd extra/
$ mkdir -p usr/dir1
$ chown 1000.1000 usr/dir1
$ chmod 700 usr/dir1
$ getfacl -n usr/dir1 >> .tcattr

You should end up with a ".tcattr" file with the content:

 ./extra/.tcattr
# file: usr/dir1
# owner: 1000
# group: 1000
user::rwx
group::---
other::---

If you want to set more attributes for other files, you just need to follow the same logic and add more entries to the .tcattr file. For example, if you want a ./extra/usr/dir1/file1 having user id 1000, group id 2000 and only read and write execution permissions for the owner and the group of this file but no permissions at all for the others, you can do the following:

$ cd extra/
$ touch usr/dir1/file1
$ chown 1000.2000 usr/dir1/file1
$ chmod 660 usr/dir1/file1
$ getfacl -n usr/dir1/file1 >> .tcattr

And after these two changes, you should have an ./extra/.tcattr file, in your host machine, with the following content:

 ./extra/.tcattr
# file: usr/dir1
# owner: 1000
# group: 1000
user::rwx
group::---
other::---
 
# file: usr/dir1/file1
# owner: 1000
# group: 2000
user::rw-
group::rw-
other::---

Note: Files and directories not explicitly listed in the ".tcattr" file will be set with default attributes: regular files (user id root, group id root, and 660 permissions) - executable files (user id root, group id root, and 0770 permissions) - directories (user id root, group id root, and 755 permissions).

Note: All .tcattr files will not be committed to the OSTree rootfs, so they will not exist in your final TorizonCore image or OSTree filesystem.

$ torizoncore-builder --help
usage: torizoncore-builder [-h] [--verbose] [--log-level LOG_LEVEL] [--log-file LOG_FILE]
                           [--bundle-directory BUNDLE_DIRECTORY] [--storage-directory STORAGE_DIRECTORY] [-v]
                           {batch,build,bundle,combine,deploy,dt,dto,images,isolate,kernel,push,serve,splash,union} ...

TorizonCore Builder is an utility that allows to create customized TorizonCore OSTree commits and Toradex Easy Installer images without rebuilding the complete operating system.

optional arguments:
  -h, --help            show this help message and exit
  --verbose             show more output
  --log-level LOG_LEVEL
                        set global log level (debug, info, warning, error, critical)
  --log-file LOG_FILE   write logs to a file instead of console
  --bundle-directory BUNDLE_DIRECTORY
                        container bundle directory
  --storage-directory STORAGE_DIRECTORY
                        path to internal storage. Must be a file system capable of carrying Linux file system metadata (Unix file permissions and xattr)
  -v, --version         show program's version number and exit

Commands:
  {batch,build,bundle,combine,deploy,dt,dto,images,isolate,kernel,push,serve,splash,union}
    batch               Automatically downloads a set of Toradex Easy Installer images and adds the specified containers to it.
    build               Customize a Toradex Easy Installer image based on settings specified via a configuration file.
    bundle              Create container bundle from a Docker Compose file. Can be used to combine with a TorizonCore base image.
    combine             Combines a container bundle with a specified Toradex Easy Installer image.
    deploy              Deploy the current image as a Toradex Easy Installer image
    dt                  Manage device trees
    dto                 Manage device tree overlays
    images              Manage Toradex Easy Installer Images.
    isolate             capture /etc changes.
    kernel              Manage and modify TorizonCore Linux Kernel.
    push                Push branch to OTA server
    serve               Serve OSTree on the local network using http
    splash              change splash screen
    union               Create a commit out of isolated changes for unpacked Toradex Easy Installer Image

Learn more on https://developer.toradex.com/knowledge-base/torizoncore-builder-tool

$ torizoncore-builder --log-level debug dt status

$ torizoncore-builder bundle --help
usage: torizoncore-builder bundle [-h] [-f COMPOSE_FILE] [--platform PLATFORM] [--host-workdir HOST_WORKDIR]
                                  [--docker-username DOCKER_USERNAME] [--docker-password DOCKER_PASSWORD]
                                  [--registry REGISTRY]

optional arguments:
  -h, --help            show this help message and exit
  -f COMPOSE_FILE, --file COMPOSE_FILE
                        Specify an alternate compose file
  --platform PLATFORM   Specify platform to make sure fetching the correct container image when multi-platform container images are specified (e.g. linux/arm/v7 or linux/arm64)
  --host-workdir HOST_WORKDIR
                        Location where Docker needs to bind mount to to share data between this script and the DIND instance.
  --docker-username DOCKER_USERNAME
                        Optional username to be used to access container image.
  --docker-password DOCKER_PASSWORD
                        Password to be used to access container image.
  --registry REGISTRY   Alternative container registry used to access container image.

$ torizoncore-builder bundle -f docker-compose.yml

$ torizoncore-builder bundle -f docker-compose.yml --platform linux/arm/v7

$ torizoncore-builder combine --help
usage: torizoncore-builder combine [-h] --image-directory IMAGE_DIRECTORY --output-directory OUTPUT_DIRECTORY
                                   [--image-name IMAGE_NAME] [--image-description IMAGE_DESCRIPTION]
                                   [--image-licence LICENCE_FILE] [--image-release-notes RELEASE_NOTES_FILE]

optional arguments:
  -h, --help            show this help message and exit
  --image-directory IMAGE_DIRECTORY
                        Path to TorizonCore Toradex Easy Installer source image, which needs to be updated with docker bundle.
  --output-directory OUTPUT_DIRECTORY
                        Path to combined TorizonCore Toradex Easy Installer image, which needs to be updated with docker bundle.
  --image-name IMAGE_NAME
                        Image name to be used in Easy Installer image json
  --image-description IMAGE_DESCRIPTION
                        Image description to be used in Easy Installer image json
  --image-licence LICENCE_FILE
                        Licence file which will be shown on image installation
  --image-release-notes RELEASE_NOTES_FILE
                        Release notes file which will be shown on image installation

$ torizoncore-builder deploy --output-directory <name of directory to store Torizon image> <name or checksum of branch from Union command>

$ torizoncore-builder deploy --remote-host <IP or hostname(.local) of target board> --remote-username <username of target board> --remote-password <password of user on target board> <name or checksum of branch from Union command>

$ torizoncore-builder deploy --output-directory <directory to store Toradex Easy Installer image of Torizon with deployment set to provided reference> <name or checksum of a branch within unpacked OSTree repo (output from union command or any other branch)>

$ torizoncore-builder deploy <name or checksum of branch within unpacked OSTree repo (output from union command or any other branch)> --remote-host <IP or hostname(.local) or remote target machine> --remote-username <user name of remote target machine> --remote-password <user password of remote target machine> --reboot <indicates reboot machine after deploying>

$ torizoncore-builder --storage-directory <Path to store intermediate data. Must be a file system capable of carrying Linux file system metadata (Unix file permissions and xattr)> deploy <name or checksum of the branch within unpacked OSTree repo (output from union command or any other branch)> --output-directory <directory to store Toradex Easy Installer image of Torizon image with deployment set to provided reference> --deploy-sysroot-directory <directory to store the intermittent deployment sysroot>

$ torizoncore-builder deploy <name or checksum of branch within unpacked OSTree repo (output from union command or any other branch)> --remote-host <IP or hostname(.local) or remote target machine> --remote-username <user name of remote target machine> --remote-password <password of remote target machine> --reboot <indicates reboot machine after deploying>

 $ torizoncore-builder dt --help
usage: torizoncore-builder dt [-h] {status,checkout,apply} ...

Manage application of device trees.

optional arguments:
  -h, --help            show this help message and exit

Commands::
  {status,checkout,apply}
    status              Show the current device tree
    checkout            Checkout the Toradex device tree and overlay repository
    apply               Compile and enable a device tree

$ torizoncore-builder dt checkout

$ torizoncore-builder dt apply -h
usage: torizoncore-builder dt apply [-h] [--include-dir DIR] DEVICE_TREE

Compile and enable a device tree

positional arguments:
  DEVICE_TREE        Path to the device tree source file

optional arguments:
  -h, --help         show this help message and exit
  --include-dir DIR  Search directory for include files during device tree compilation.
                     Can be passed multiple times. If absent, defaults to 'device-trees/include'.

$ torizoncore-builder dt apply device-trees/dts-arm64/imx8qxp-colibri-aster.dts
<...>
/tmp/tmpiyorpx7w: Device Tree Blob version 17, size=120412, boot CPU=0, string block size=7360, DT structure block size=112996
Device tree imx8qxp-colibri-aster.dtb successfully applied.

$ torizoncore-builder dt status
Current device tree is: imx8qxp-colibri-aster.dtb

$ torizoncore-builder dto --help
usage: torizoncore-builder dto [-h] {apply,list,status,remove,deploy} ...

Manage device tree overlays

optional arguments:
  -h, --help            show this help message and exit

Commands:knowledge-base/toradex-easy-installer-os-and-demo-images#TorizonCore_Embedded_Linux_Images
  {apply,list,status,remove,deploy}
    apply               Apply a device tree overlay
    list                List the device tree overlays compatible with the current device tree
    status              List the applied device tree overlays
    remove              Remove a device tree overlay
    deploy              Deploy a device tree overlay in the device

$ torizoncore-builder dto apply --help
usage: torizoncore-builder dto apply [-h] [--include-dir DIR] [--device-tree FILE] [--force] OVERLAY

Apply a further overlay to the current device tree.

positional arguments:
  OVERLAY             Path to the overlay source file

optional arguments:
  -h, --help          show this help message and exit
  --include-dir DIR   Search directory for include files during overlay compilation. Can be passed multiple times.
                      If absent, defaults to 'device-trees/include'.
  --device-tree FILE  Test overlay application over this device tree blob instead of the current device tree.
  --force             Apply the overlay even on failure checking it against the current device tree.

$ torizoncore-builder dto apply device-trees/overlays/colibri-imx8x_dsihdmi_overlay.dts
/tmp/tmpfmxpe871: Device Tree Blob version 17, size=2323, boot CPU=0, string block size=275, DT structure block size=1992
Overlay 'device-trees/overlays/colibri-imx8x_dsihdmi_overlay.dts' compiles successfully.
/tmp/tmpp64__jp9: Device Tree Blob version 17, size=121434, boot CPU=0, string block size=7462, DT structure block size=113916
Overlay colibri-imx8x_dsihdmi_overlay.dtbo successfully applied.

$ torizoncore-builder dto list --help
usage: torizoncore-builder dto list [-h] [--device-tree FILE]

List overlays compatible to the current device tree.

optional arguments:
  -h, --help          show this help message and exit
  --device-tree FILE  Check for overlay compatibility against this device tree blob instead of the current device tree.

 $ torizoncore-builder dto list
Overlays compatible with device tree imx8qxp-colibri-aster.dtb:
- device-trees/overlays/colibri-imx8x_ad7879_overlay.dts
- device-trees/overlays/colibri-imx8x_atmel-mxt_overlay.dts
- device-trees/overlays/colibri-imx8x_dsihdmi_overlay.dts
- device-trees/overlays/colibri-imx8x_parallel-rgb_overlay.dts
- device-trees/overlays/display-dpi-lt170410_overlay.dts

 $ torizoncore-builder dto status --help
usage: torizoncore-builder dto status [-h]

List the applied overlays.

optional arguments:
  -h, --help  show this help message and exit

$ torizoncore-builder dto status
Enabled overlays over device tree imx8qxp-colibri-aster.dtb:
- colibri-imx8x_dsihdmi_overlay.dtbo
- colibri-imx8x_atmel-mxt_overlay.dtbo

$ torizoncore-builder dto remove --help
usage: torizoncore-builder dto remove [-h] [--all] [OVERLAY]

Remove an overlay that is not yet deployed.

positional arguments:
  OVERLAY     Name of the device tree overlay blob

optional arguments:
  -h, --help  show this help message and exit
  --all       Remove all overlays instead.

$ torizoncore-builder dto remove colibri-imx8x_dsihdmi_overlay.dtbo

$ torizoncore-builder dto deploy --help
usage: torizoncore-builder dto deploy [-h] --remote-host REMOTE_HOST --remote-username REMOTE_USERNAME --remote-password REMOTE_PASSWORD [--reboot] [--mdns-source MDNS_SOURCE] [--include-dir DIR]
                                      [--force] [--device-tree FILE] [--clear]
                                      OVERLAY [OVERLAY ...]

Deploy a device tree overlay in the device

positional arguments:
  OVERLAY               Path to the device tree overlay source file(s)

optional arguments:
  -h, --help            show this help message and exit
  --remote-host REMOTE_HOST
                        Name/IP of remote machine
  --remote-username REMOTE_USERNAME
                        User name of remote machine
  --remote-password REMOTE_PASSWORD
                        Password of remote machine
  --reboot              Reboot device after deploying device tree overlay(s)
  --mdns-source MDNS_SOURCE
                        Use the given IP address as mDNS source. This is useful when multiple interfaces are used, and mDNS multicast requests are sent out the wrong network interface.
  --include-dir DIR     Search directory for include files during overlay compilation. Can be passed multiple times. If absent, defaults to 'device-trees/include'
  --force               Apply the overlay even on failure checking it against a device tree.
  --device-tree FILE    Test the overlay against a specific device tree.
  --clear               Remove all currently applied device tree overlays.

$ torizoncore-builder dto deploy --remote-host <Hostname/IP address of target board> --remote-username <User on target board> --remote-password <Password of user on target board> --force --reboot device-trees/overlays/display-lt161010_overlay.dts 
Downloading image from: https://artifacts.toradex.com/artifactory/torizoncore-oe-prod-frankfurt/dunfell-5.x.y/release/1/verdin-imx8mm/torizon/torizon-core-docker/oedeploy/torizon-core-docker-verdin-imx8mm-Tezi_5.1.0+build.1.tar

The download may take some time. Please wait...
Download Complete!

Unpacking Toradex Easy Installer image.
Copying Toradex Easy Installer image.
Unpacking TorizonCore Toradex Easy Installer image.
Importing OSTree revision 8c514a595469283bb69603f2fa32395b5dbbc3d80a8f9d824dc661f1b68c4d82 from local repository...
0 metadata, 0 content objects imported; 0 bytes content written                                                                                                                                            
Unpacked OSTree from Toradex Easy Installer image:
  Commit checksum: 8c514a595469283bb69603f2fa32395b5dbbc3d80a8f9d824dc661f1b68c4d82
  TorizonCore Version: 5.1.0+build.1
'device-trees' directory already exists
'display-lt161010_overlay.dts' compiles successfully.
warning: --force was used, bypassing checking overlays against the device tree.
Overlay display-lt161010_overlay.dtbo successfully applied.
Commit 40aec4200054c9865aa6e0b13acdeb9ed63ac5a91e9276800e4a22850f42d84b has been generated for changes and ready to be deployed.
Pulling OSTree with ref dto_deploy (checksum 40aec4200054c9865aa6e0b13acdeb9ed63ac5a91e9276800e4a22850f42d84b) from local archive repository...
Starting http server to serve OSTree.
Starting OSTree pull on the device...
Deploying new OSTree on the device...
Deploying successfully finished.
Device reboot initiated...

$ torizoncore-builder images --help
usage: torizoncore-builder images [-h] [--remove-storage] {download,unpack} ...

optional arguments:
  -h, --help         show this help message and exit
  --remove-storage   Automatically clear storage prior to unpacking a new Easy Installer image.

Commands:
  {download,unpack}
    download         Download image from Toradex Artifactory and unpack it.
    unpack           Unpack a specified Toradex Easy Installer image so it can be modified with
                     union subcommand.

$ torizoncore-builder images download --remote-host <hostname/IP address of target board> --remote-username <username on target board> --remote-password <password of user on target board>

$ torizoncore-builder images download --remote-host <hostname/IP address of target board> --remote-username <username on target board> --remote-password <password of user on target board>

$ torizoncore-builder --storage-directory <path to user storage directory> images download --remote-host <hostname/IP address of target board> --remote-username <username on target board> --remote-password <password of user on target board>

$ torizoncore-builder images unpack <base Toradex Easy Installer image of Torizon>

$ torizoncore-builder images unpack <path to base Toradex Easy Installer image of Torizon in the working directory>

$ torizoncore-builder --storage-directory <path to user storage directory> images unpack <path to base Toradex Easy Installer image of Torizon in working directory>

'gshadow', 'machine-id', 'group', 'shadow', 'systemd/system/sysinit.target.wants/run-postinsts.service',
'ostree/remotes.d/toradex-nightly.conf', 'docker/key.json', '.updated', '.pwd.lock', 'group-',
'gshadow-', 'hostname', 'ssh/ssh_host_rsa_key', 'ssh/ssh_host_rsa_key.pub', 'ssh/ssh_host_ecdsa_key',
'ssh/ssh_host_ecdsa_key.pub','ssh/ssh_host_ed25519_key','ssh/ssh_host_ed25519_key.pub',
'ipk-postinsts', 'fw_env.conf'

$ torizoncore-builder isolate --help
usage: torizoncore-builder isolate [-h] [--changes-directory CHANGES_DIR] [--force]
                                   --remote-host REMOTE_HOST --remote-username REMOTE_USERNAME 
                                   --remote-password REMOTE_PASSWORD [--mdns-source MDNS_SOURCE]

optional arguments:
  -h, --help            show this help message and exit
  --changes-directory CHANGES_DIR
                        Directory to save the isolated changes from the device. Must be a file system capable of carrying Linux file system metadata (Unix file permissions and xattr). If not passed,
                        defaults to a directory in the storage volume.
  --force               Force removal of storage changes directory
  --remote-host REMOTE_HOST
                        name/IP of remote machine
  --remote-username REMOTE_USERNAME
                        user name of remote machine
  --remote-password REMOTE_PASSWORD
                        password of remote machine
  --mdns-source MDNS_SOURCE
                        Use the given IP address as mDNS source. This is useful when multiple interfaces are used, and mDNS multicast requests are sent out the wrong network interface.

$ torizoncore-builder kernel --help
usage: torizoncore-builder kernel [-h] {build_module,set_custom_args,get_custom_args,clear_custom_args} ...

optional arguments:
  -h, --help            show this help message and exit

Commands:
  {build_module,set_custom_args,get_custom_args,clear_custom_args}
    build_module        Build the kernel module at the provided source directory.
    set_custom_args     Set the TorizonCore kernel arguments.
    get_custom_args     Get the TorizonCore kernel arguments.
    clear_custom_args   Clear the TorizonCore kernel arguments.

$ torizoncore-builder kernel build_module --help
usage: torizoncore-builder kernel build_module [-h] [--autoload] [SRC_DIR]

positional arguments:
  SRC_DIR     Path to directory with kernel module source code.

optional arguments:
  -h, --help  show this help message and exit
  --autoload  Configure kernel module to be loaded on startup.

$ torizoncore-builder kernel set_custom_args --help
usage: torizoncore-builder kernel set_custom_args [-h] KERNEL_ARGS [KERNEL_ARGS ...]

positional arguments:
  KERNEL_ARGS  Kernel arguments to be added.

optional arguments:
  -h, --help   show this help message and exit

$ torizoncore-builder kernel set_custom_args "param1=val1" "param2=val2"
'custom-kargs_overlay.dts' compiles successfully.
Overlay custom-kargs_overlay.dtbo successfully applied.
Kernel custom arguments successfully configured with "param1=val1 param2=val2".

$ torizoncore-builder kernel get_custom_args --help
usage: torizoncore-builder kernel get_custom_args [-h]

optional arguments:
  -h, --help  show this help message and exit

$ torizoncore-builder kernel get_custom_args
Currently configured custom kernel arguments: "param1=val1 param2=val2".

$ torizoncore-builder kernel clear_custom_args --help
usage: torizoncore-builder kernel clear_custom_args [-h]

optional arguments:
  -h, --help  show this help message and exit

$ torizoncore-builder kernel clear_custom_args
Custom kernel arguments successfully cleared.

$ torizoncore-builder serve --help
usage: torizoncore-builder serve [-h] [--ostree-repo-directory OSTREE_REPO_DIRECTORY]

optional arguments:
  -h, --help            show this help message and exit
  --ostree-repo-directory OSTREE_REPO_DIRECTORY
                        Path to the OSTree repository to serve (defaults to internal archive repository).

torizoncore-builder push [-h] --credentials CREDENTIALS [--repo OSTREE] [--hardwareid HARDWAREIDS] [--package-name TARGET] [--package-version VERSION] [--verbose] [REF]

$ torizoncore-builder splash --help
usage: torizoncore-builder splash [-h] --image IMAGE [--work-dir WORK_DIR]

optional arguments:
  -h, --help           show this help message and exit
  --image IMAGE        Path and name of splash screen image
  --work-dir WORK_DIR  Working directory

usage: torizoncore-builder union [-h] [--changes-directory CHANGES_DIRS]
                                 [--extra-changes-directory EXTRA_CHANGES_DIRS]
                                 --union-branch UNION_BRANCH
                                 [--subject SUBJECT] [--body BODY]

optional arguments:
  -h, --help            show this help message and exit
  --changes-directory CHANGES_DIRS
                        Path to the directory containing user changes. Can be specified multiple times!
  --extra-changes-directory EXTRA_CHANGES_DIRS
                        Additional path with user changes to be committed. Can be specified multiple times!
  --union-branch UNION_BRANCH
                        Name of branch containing the changes committed to the unpacked repo.
  --subject SUBJECT     OSTree commit subject. Defaults to "TorizonCore Builder [timestamp]"
  --body BODY           OSTree commit body message

$ cd extra/
$ mkdir -p usr/dir1
$ chown 1000.1000 usr/dir1
$ chmod 700 usr/dir1
$ getfacl -n usr/dir1 >> .tcattr

 ./extra/.tcattr
# file: usr/dir1
# owner: 1000
# group: 1000
user::rwx
group::---
other::---

$ cd extra/
$ touch usr/dir1/file1
$ chown 1000.2000 usr/dir1/file1
$ chmod 660 usr/dir1/file1
$ getfacl -n usr/dir1/file1 >> .tcattr

 ./extra/.tcattr
# file: usr/dir1
# owner: 1000
# group: 1000
user::rwx
group::---
other::---
 
# file: usr/dir1/file1
# owner: 1000
# group: 2000
user::rw-
group::rw-
other::---