Search by Tags

TorizonCore Builder Tool - Commands Manual

 

  1. TorizonCore Builder - 3.0.0 and Later
    1. Introduction
    2. Requirements
    3. TorizonCore Builder and OSTree
    4. The torizoncore-builder command
      1. Usage
    5. The Build Command
      1. Usage
    6. The Bundle Command
      1. Usage
    7. The Combine Command
      1. Usage
    8. The Deploy Command
      1. Usage
      2. Arguments
      3. Example
    9. The Dt (Device Tree) Command
      1. dt checkout
      2. dt apply
      3. dt status
    10. The Dto (Device Tree Overlay) Command
      1. dto apply
      2. dto list
      3. dto status
      4. dto remove
      5. dto deploy
    11. The Images Command
      1. images download
      2. Usage
      3. Arguments
      4. Example
      5. images unpack
      6. Example
    12. The Isolate Command
      1. Usage
      2. Example
    13. The Kernel Command
      1. kernel buildmodule
      2. kernel setcustomargs
      3. kernel getcustomargs
      4. kernel clearcustomargs
    14. The OSTree Command
      1. Usage
      2. ostree serve
      3. Usage
    15. The Push Command
      1. Usage
      2. Arguments
      3. Example
    16. The Splash Command
      1. Usage
    17. The Union Command
      1. Usage
    18. Setting attributes to files and directories using the ".tcattr" file
      1. Example of creating a ".tcattr" file for an additional changes directory
  2. TorizonCore Builder - Before 3.0.0
    1. Introduction
    2. Requirements
    3. TorizonCore Builder and OSTree
    4. The torizoncore-builder command
      1. Usage
    5. The Bundle Command
      1. Usage
    6. The Combine Command
      1. Usage
    7. The Deploy Command
      1. Usage
      2. Arguments
      3. Example
    8. The Dt (Device Tree) Command
      1. dt checkout
      2. dt apply
      3. dt status
    9. The Dto (Device Tree Overlay) Command
      1. dto apply
      2. dto list
      3. dto status
      4. dto remove
      5. dto deploy
    10. The Images Command
      1. images download
      2. Usage
      3. Arguments
      4. Example
      5. images unpack
      6. Example
    11. The Isolate Command
      1. Usage
      2. Example
    12. The Kernel Command
      1. kernel buildmodule
      2. kernel setcustomargs
      3. kernel getcustomargs
      4. kernel clearcustomargs
    13. The OSTree Command
      1. ostree serve
      2. Usage
    14. The Push Command
      1. Usage
      2. Arguments
      3. Example
    15. The Splash Command
      1. Usage
    16. The Union Command
      1. Usage
    17. Setting attributes to files and directories using the ".tcattr" file
      1. Example of creating a ".tcattr" file for an additional changes directory
Article updated at 31 Aug 2021
Subscribe for this article updates

Select the version of your OS from the tabs below. If you don't know the version you are using, run the command cat /etc/os-release or cat /etc/issue on the board.



Remember that you can always refer to the Torizon Documentation, there you can find a lot of relevant articles that might help you in the application development.

TorizonCore Builder - 3.0.0 and Later

Introduction

TorizonCore Builder is a tool that enables customizations such as include a splash screen, an overlay, preinstalled containers, capture 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

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 OTA.

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] [--storage-directory STORAGE_DIRECTORY] [-v]
                           {build,bundle,combine,deploy,dt,dto,images,isolate,kernel,ostree,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
  --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:
  {build,bundle,combine,deploy,dt,dto,images,isolate,kernel,ostree,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
    push                Push branch to OTA server
    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.

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-release-notes RELEASE_NOTES_FILE] 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-release-notes RELEASE_NOTES_FILE
                        Release notes file which will be shown on image installation

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, make it default deployment. Deployment can be either set on an unpacked Toradex Easy Installer image of Torizon or directly on the target board after creating an ssh session.

Suppose deployment is to be set on the unpacked Toradex Easy Installer image of Torizon. In that case, it makes a directory (inside the bind-mounted working directory) with a user-provided name and stores the Torizon image in it as output.

If pre-installed container(s) are needed, the combine command is necessary to create a new Toradex Easy Installer image of Torizon with a bundled container(s) from the bundle command.

Usage

Note: Output directory is not needed to be created.

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

If the deployment is to be set on the target board, the user needs to provide hostname or IP, username, and password.

$ 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>

Arguments

--output-directory: directory to store Toradex Easy Installer image of Torizon with deployment set to branch from union command. The output directory should not be created by the user.

--remote-host: remote target machine IP or hostname (.local)

--remote-username: username of the remote target machine

--remote-password: user password of the remote target machine

--reboot: reboot remote target machine after deploying default: do not reboot after deployment

--deploy-sysroot-directory (optional): directory to store the intermittent deployment sysroot (used internally by the tool). default: docker volume mounted at /deploy

Note: OSTree needs to be able to write extended attributes in this directory. Better to be used without Docker volume option.

Positional Argument

branch name/checksum to be deployed from union command default: active deployment in OSTree repo

Example

with Docker volume

To create an output image

$ 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)>

To set branch for deployment on the remote target machine.

$ 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>

without Docker volumes

To create an output image:

$ 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>

To set branch for deployment on a remote target machine

$ 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>

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.

Usage

$ torizoncore-builder dt checkout

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 dt deploy).

Usage

$ 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'.

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 (see dt deploy).

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 TEZI 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 [--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.

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> --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,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.

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>

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

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>

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>

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 [--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.

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.

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 Push Command

The push command will take an image referenced by an OSTree repo or a docker-compose.yml file, will sign with the certificates from a given Torizon OTA account credentials, and will push it to the same Torizon OTA account for an OTA deployment.

Usage

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

Arguments

--credentials: Relative path to the credentials.zip file obtained by the user Torizon OTA account.

--repo (optional): OSTree repository to push from.

--hardwareid (optional): Hardware IDs to use when creating and signing targets.json.

--package-name (optional): Package name for docker-compose file.

--package-version (optional): Package version for docker-compose file.

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

Example

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

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 - Before 3.0.0

Introduction

TorizonCore Builder is a tool that enables customizations such as include a splash screen, an overlay, preinstalled containers, capture 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

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 OTA.

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]
                           [--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

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 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] [-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.

Example

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

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

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

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

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] --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

The Deploy Command

deploy takes a branch(containing the commit for changes) from the union command, make it default deployment. Deployment can be either set on an unpacked Toradex Easy Installer image of Torizon or directly on the target board after creating an ssh session.

Suppose deployment is to be set on the unpacked Toradex Easy Installer image of Torizon. In that case, it makes a directory (inside the bind-mounted working directory) with a user-provided name and stores the Torizon image in it as output.

If pre-installed container(s) are needed, the combine command is necessary to create a new Toradex Easy Installer image of Torizon with a bundled container(s) from the bundle command.

Usage

Note: Output directory is not needed to be created.

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

If the deployment is to be set on the target board, the user needs to provide hostname or IP, username, and password.

$ 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>

Arguments

--output-directory: directory to store Toradex Easy Installer image of Torizon with deployment set to branch from union command. The output directory should not be created by the user.

--remote-host: remote target machine IP or hostname (.local)

--remote-username: username of the remote target machine

--remote-password: user password of the remote target machine

--reboot: reboot remote target machine after deploying default: do not reboot after deployment

--deploy-sysroot-directory (optional): directory to store the intermittent deployment sysroot (used internally by the tool). default: docker volume mounted at /deploy

Note: OSTree needs to be able to write extended attributes in this directory. Better to be used without Docker volume option.

Positional Argument

branch name/checksum to be deployed from union command default: active deployment in OSTree repo

Example

with Docker volume

To create an output image

$ 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)>

To set branch for deployment on the remote target machine.

$ 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>

without Docker volumes

To create an output image:

$ 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>

To set branch for deployment on a remote target machine

$ 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>

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.

Usage

$ torizoncore-builder dt checkout

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 dt deploy).

Usage

$ 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'.

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: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

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 (see dt deploy).

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 TEZI 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 [--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.

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> --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,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.

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>

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

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>

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>

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 [--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.

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.

ostree serve

Serve an OSTree repository via HTTP.

Usage

$ 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).

The Push Command

The push command will take an image referenced by an OSTree repo or a docker-compose.yml file, will sign with the certificates from a given Torizon OTA account credentials, and will push it to the same Torizon OTA account for an OTA deployment.

Usage

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

Arguments

--credentials: Relative path to the credentials.zip file obtained by the user Torizon OTA account.

--repo (optional): OSTree repository to push from.

--hardwareid (optional): Hardware IDs to use when creating and signing targets.json.

--package-name (optional): Package name for docker-compose file.

--package-version (optional): Package version for docker-compose file.

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

Example

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

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] --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

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]
                                 [--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

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.