Search by Tags

Capturing Changes in the Configuration of a Board on TorizonCore


Article updated at 17 Feb 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.

Torizon 5.0.0


During the development process with TorizonCore, usually it is required to capture configuration changes on the /etc directory that needs to be committed to the TorizonCore image.

Here are some examples of procedures that require changes in the configuration of the system:

This article shows how to capture these system configurations.

This article complies to the Typographic Conventions for Torizon Documentation.


The pre-requisite to complete these instructions are:

Installing TorizonCore Builder

To install TorizonCore Builder, follow the instructions below, in order.

Create and enter a working directory where your customization will be stored:

$ mkdir ~/tcbworkdir
$ cd ~/tcbworkdir

Use the setup script named, available on the Toradex Github, to setup TorizonCore Builder:

$ wget
$ source

Verify that the command torizoncore-builder is available:

$ torizoncore-builder --help

Warning: Make sure to: (1) source the script, (2) every time you open a new terminal, (3) inside the working directory you have previously created. Otherwise, it will not work as intended and, most importantly, the torizoncore-builder alias will not be created properly.

Capturing Changes in the Configuration of a Board

If you have made any configuration changes, they will be saved in the /etc directory of your board. The isolate command will fetch all those changes (modifications, addition, deletion, and files and directories permissions and ownership). It requires an SSH connection for the communication between the host PC and the target board.

Get configuration changes from the target board, saving them in a specific directory, in this case changes1, with this command:

$ torizoncore-builder isolate --remote-host --remote-username torizon --remote-password torizon --changes-directory changes1
Changes in /etc successfully isolated.

Change the arguments --remote-host,--remote-username and --remote-password to your board IP Address, username and password, respectively.

Tip: From TorizonCore Builder 3.1.0 after, the default value of --remote-username and --remote-password is torizon, so if the username or the password is torizon the argument can be omitted.

Tip: In order to keep credentials (files and directories permissions and ownership) the isolate command will create the file /etc/.tcattr which will be automatically used later by the union command.

Applying Captured Changes to a Custom Image

There are two possible approaches to apply the captured changes to the custom Toradex Easy Installer image, described in the next two sections Approach 1 and Approach 2. These approaches in some cases are interchangeable and in some not as described in the next sections.

Attention: To understand when to use each, you should read them in sequence. However, they both generate a custom Toradex Easy Installer image as output, so the commands should be followed separately and not in sequence.

Approach 1: Applying Changes to a Custom Image: Using the Build Command

TorizonCore Builder build command generates a custom TorizonCore image with the captured changes, ready to be installed with Toradex Easy Installer, named deployed_image in the example below. This is achieved using a configuration YAML file, tcbuild.yml as default. It requires a downloaded TorizonCore image, torizon-core-docker-colibri-imx6-Tezi_5.3.0+build.7.tar in this case, as input. The directory (or directories) with the captured configuration changes is passed as customization: filesystem.

# Sample configuration file:
    local: images/torizon-core-docker-colibri-imx6-Tezi_5.3.0+build.7.tar
#Sample customization: insert the configuration changes made in the device
     - changes1/
    local: deployed_image

Build The Custom Image

To generate the TorizonCore image, run the command below, in the same directory where the tcbuild.yml file is:

$ torizoncore-builder build

In case of using a configuration file with a different name than tcbuild.yml, run the command specifying the configuration file name:

$ torizoncore-builder build -f <configuration_file_name>

Deploy The Custom Toradex Easy Installer Image

To deploy the custom Toradex Easy Installer image to the board, click on the link below and choose between the available options.

Deploy The Custom Toradex Easy Installer Image

Considerations About Approach 1

This approach, with the build command, may be easier to follow for the first time. This is why it is the one used in Torizoncore Builder - Getting Started. Integrating several customizations, such as including a splash screen or a custom device tree, is just a matter of adding all of them to the customization YAML file. This makes this approach also interesting to use on your CI/CD pipelines.

However, every time the build command is executed it runs a full pipeline (cycle) from scratch: it unpacks an input image, applies all the customization, and creates an output custom image. If you plan to make incremental changes, it may become too slow and possibly annoying to run build every time. Luckily, it is possible to avoid running a full pipeline, and it is described in the next section.

Approach 2: Applying Changes to a Custom Image: Using Interactive Commands

Although this approach has a steeper learning curve, it is more granular. In other words, you don't have to run a full pipeline every time you make a change, thus saving time if you are making incremental customization or tests. Also, this approach may be more flexible as you will learn in this section.

The differences of this approach are especially useful when generating multiple different custom Toradex Easy Installer images, with a different directory containing the captured changes for each image, in an automated script for example. Specifying the directory with the captured changes included in the image is just a matter of passing a different --changes-directory argument to the union command. Also, it is not necessary to unpack the image every time, needing just the union and the deploy command in sequence to generate the custom Toradex Easy Installer image (the isolate command is still necessary to capture the changes in the device into a directory in the host machine).

To capture the changes in the device with this approach, follow the sequence below.

Unpack an Input Image

You just need to execute this once. Then, you are ready to apply multiple changes to the image. For example, in addition to capturing changes iteratively, you can also apply a custom splash screen, a new device tree, among other possibilities.

If you have not unpacked an image yet, download a base TorizonCore image inside the TorizonCore Builder working directory, then unpack it. In the example below the torizon-core-docker-colibri-imx6-Tezi_5.3.0+build.7.tar image is used as reference:

$ torizoncore-builder images unpack torizon-core-docker-colibri-imx6-Tezi_5.3.0+build.7.tar

If you want to change the TorizonCore base image, download the new image and run the images unpack command again, passing the new image as the argument.

Merge Changes

As a reminder, you must have captured changes as explained previously.

Merge changes (as well as other customizations like a kernel module or a device tree) to the base Toradex Easy Installer image of Torizon - use whatever branch name you want. As an example, to commit changes into a branch named custom-branch use the command below, accordingly with the TorizonCore Builder version:

$ torizoncore-builder union custom-branch --changes-directory changes1
$ torizoncore-builder union --union-branch=custom-branch --changes-directory changes1

Warning: We recommend that you switch to the latest version of TorizonCore Builder to enjoy its simpler and more consistent user interface besides other improvements and bug fixes.

Deploy The Custom Toradex Easy Installer Image

To deploy the custom Toradex Easy Installer image to the board, click on the link below and choose between the available options.

Deploy The Custom Toradex Easy Installer Image