Skip to main content
Version: Torizon OS 7.x.y

TorizonCore Builder Tool - Commands Manual

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 Torizon OS in an easy way. The end result is a custom Torizon OS 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 Updates.

The torizoncore-builder command​

info

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 /torizon/in-depth/torizoncore-builder/torizoncore-builder-tool-customizing-torizoncore-images

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).
  --cacert-to REGISTRY CERTIFICATE
                        Define a root CA CERTIFICATE (path to file in PEM format) to be used for
                        validating the certificate of the specified secure REGISTRY (when
                        connecting to it).
  --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"
info

For more information about how to use the bundle command with Private Registries, read Remarks About using private registries

Limitations and Known Issues​

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.

info

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: Torizon OS 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.

info

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​

caution

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 our Torizon Cloud features, such as secure updates, devices monitoring, and new features to be released.

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 Cloud 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 Cloud (using credentials contained in the "online data" coming from a certain Torizon Cloud 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] [--hibernated]
                                            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).
  --hibernated          
                        (Torizon OS 6.8+) Add flag to auto-provision in hibernated mode. 
                        Hibernated devices are registered, but cannot receive updates from 
                        Torizon Cloud nor send data to it.

--hibernated is currently only available in the early-access version of TCB. For more details about this version, check the setup script section.

images serve​

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

danger

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​

caution

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

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

./images/image_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.

info

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/image_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​

info

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.

    'group-',
    'shadow-',
    'gshadow-',
    'hostname',
    'machine-id',
    'ipk-postinsts',
    'fw_env.conf',
    'docker/key.json',
    '.updated',
    '.pwd.lock',
    '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',
    'systemd/system/sysinit.target.wants/run-postinsts.service',
    'ostree/remotes.d/toradex-nightly.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 Torizon OS article.

The Kernel Command​

kernel is used to make modifications related to the Linux kernel of Torizon OS.

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

Build a kernel module from sources and stores the binary to be deployed to a Torizon OS 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 set_custom_args​

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.

caution

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 get_custom_args​

Get the custom arguments to be passed to the Torizon OS 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 clear_custom_args​

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 Cloud (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,static-delta}
    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.
    static-delta        Commands for managing static deltas on Torizon Cloud.

platform lockbox​

Generates a Lockbox by fetching the metadata from Torizon Cloud, 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] [--login-to REGISTRY USERNAME PASSWORD]
                                            [--cacert-to REGISTRY CERTIFICATE] [--dind-param DIND_PARAM]
                                            [--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.
  --login-to REGISTRY USERNAME PASSWORD
                        Request that the tool logs in to registry REGISTRY using specified USERNAME and PASSWORD (can
                        be employed multiple times).
  --cacert-to REGISTRY CERTIFICATE
                        Define a root CA CERTIFICATE (path to file in PEM format) to be used for validating the
                        certificate of the specified secure REGISTRY (when connecting to it).
  --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.
  --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 Cloud, run the command below:

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

platform provisioning-data​

Fetch provisioning data for secure updates.

More information on what types of provisioning data exist is available on Production Programming in Torizon page.

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.

info

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) a docker-compose file or generic package and upload it to the Torizon Cloud 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 deployment to devices using remote or offline updates.

Usage​

$ torizoncore-builder platform push --help
usage: torizoncore-builder platform push [-h] [--credentials CREDENTIALS] [--repo OSTREE] [--hardwareid HARDWAREIDS]
                                         [--description DESCRIPTION] [--package-name TARGET] [--package-version VERSION]
                                         [--compatible-with SHA256] [--canonicalize | --no-canonicalize]
                                         [--login USERNAME PASSWORD] [--login-to REGISTRY USERNAME PASSWORD]
                                         [--cacert-to REGISTRY CERTIFICATE] [--canonicalize-only] [--force] [--verbose]
                                         REF

positional arguments:
  REF                   OSTree reference, docker-compose or generic package 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
                        Define the hardware ID which the package is compatible with; this can be specified multiple 
                        times. Use only with OSTree and generic packages.
  --description DESCRIPTION
                        Add a description to the package
  --package-name TARGET
                        Package name for docker-compose or generic package file (default: name of file being pushed to OTA) 
                        or OSTree reference (default: same as REF).
  --package-version VERSION
                        Package version for docker-compose or generic package file 
                        (default: current date in the 'yyyy-mm-dd' format) or OSTree reference (default: OSTree subject).
  --compatible-with SHA256
                        Restrict an application package so it can only be installed with a compatible OS image.
                        OS image hash must be accessible in your Platforms account; Pass the string
                        'sha256=<hash>' as parameter to this switch; The switch can be used multiple times.
  --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.
  --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).
  --cacert-to REGISTRY CERTIFICATE
                        Define a root CA CERTIFICATE (path to file in PEM format) to be used for validating the
                        certificate of the specified secure REGISTRY (when connecting to it).
  --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
  --custom-meta CUSTOM_META
                        Custom Uptane metadata for the package.

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

platform static-delta create​

Create and upload to Torizon Cloud a static delta (difference in the changed files) of an OS package update.

This approach helps distributing updates more efficiently by transmitting only the delta.

Usage​

$ platform static-delta create --help
usage: torizoncore-builder platform static-delta create [-h] --credentials
                                                        CREDENTIALS
                                                        FROM_HASH TO_HASH

positional arguments:
  FROM_HASH             The OSTree commit to create a static delta from
  TO_HASH               The OSTree commit to create a static delta to

optional arguments:
  -h, --help            show this help message and exit
  --credentials CREDENTIALS
                        Relative path to credentials.zip.

Static delta generation pre-computes a binary diff between two specific OS
packages, making that particular upload path more efficient. You must specify
the 'from' and 'to' packages by their sha256 commit ID.

Example​

After uploading an OS package and a updated version of this package to the Torizon Cloud, get the HASH of the old and new versions.

$ torizoncore-builder platform static-delta --credentials credentials.zip FROM_HASH TO_HASH

The Push Command​

caution

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 Torizon OS 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.

info

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 Torizon OS 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 Torizon OS, 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::---
info

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

info

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



Send Feedback!