Warning: the Torizon Update System is a project currently under development at Toradex Labs. It is still an experimental project in it's early stages which is subject to changes without notice. This might impact new releases and/or iterations.
OSTree is a library - actually libostree - that handles updates for filesystem trees, that is, the entire Linux image. It applies updates atomically, therefore guaranteeing the system integrity in case of a failure provided by a power-cut or dropped internet connectivity for instance. Different from the A/B partition mechanism of updates, OSTree works in a git-like model, providing file updates and thus saving storage space as well as connection bandwidth and allowing more than 2 software revisions on the device at the same time. In addition, some directories such as /var and /etc and handled as special cases, providing persistent configuration and user data to be preserved between updates.
OSTree is a key technology used by the Torizon Update System, but it is not meant to be used standalone. That being said, this article shows how to use OSTree directly from command-line, for demonstration purposes.
This article complies to the Typographic Conventions for Torizon Documentation.
Here's a quick demo on performing an update using the underlying OSTree technology on the device manually. It helps to understand how things are done, which can then be used for automation.
Whenever you build TorizonCore a directory
ostree_repo gets produced during the build. This directory is git-like containing the meta-data for that build's filesystem. Toradex uploads the nightly and release Torizon builds OSTree repository and makes them available. Feeds can be found at the following location:
Attention: All device commands must be executed as root, so you have to login as root on the device or, if you are logged-in using the torizon user, prefix the following command lines with "sudo" to execute them as root.
Here is an example how to update using the Toradex feeds.
# ostree remote add --no-gpg-verify toradex-nightly \ http://feeds.toradex.com/ostree/torizon-master/nightly/apalis-imx6/
# ostree remote refs toradex-nightly toradex-nightly:apalis-imx6/torizon-rt/torizon-core-balena-rt toradex-nightly:apalis-imx6/torizon-rt/torizon-core-balena-rt-torizon-core-balena-rt toradex-nightly:apalis-imx6/torizon-rt/torizon-core-docker-rt toradex-nightly:apalis-imx6/torizon-rt/torizon-core-docker-rt-torizon-core-docker-rt toradex-nightly:apalis-imx6/torizon-rt/torizon-core-lite toradex-nightly:apalis-imx6/torizon-rt/torizon-core-lite-torizon-core-lite toradex-nightly:apalis-imx6/torizon-rt/torizon-core-podman-rt toradex-nightly:apalis-imx6/torizon-rt/torizon-core-podman-rt-torizon-core-podman-rt toradex-nightly:apalis-imx6/torizon/torizon-core-balena toradex-nightly:apalis-imx6/torizon/torizon-core-balena-torizon-core-balena toradex-nightly:apalis-imx6/torizon/torizon-core-docker toradex-nightly:apalis-imx6/torizon/torizon-core-docker-torizon-core-docker toradex-nightly:apalis-imx6/torizon/torizon-core-lite toradex-nightly:apalis-imx6/torizon/torizon-core-lite-torizon-core-lite toradex-nightly:apalis-imx6/torizon/torizon-core-podman toradex-nightly:apalis-imx6/torizon/torizon-core-podman-torizon-core-podman
# ostree pull toradex-nightly:apalis-imx6/torizon/torizon-core-podman 32 metadata, 53 content objects fetched; 51978 KiB transferred in 21 seconds
ostree diffcan be used:
# ostree diff toradex-nightly:apalis-imx6/torizon/torizon-core-podman M /usr/package.manifest M /usr/etc/manifest.xml ...
# ostree admin deploy toradex-nightly:apalis-imx6/torizon/torizon-core-podman Copying /etc changes: 6 modified, 1 removed, 7 added Transaction complete; bootconfig swap: yes; deployment count change: 1
# ostree admin status torizon e3352d041d1e52a3c6bd7aa1c4247c3e46e07e4eb9a902b457fe778f8250eb84.0 (pending) origin refspec: toradex-nightly:apalis-imx6/torizon/torizon-core-podman * torizon 62f27eb28b9fd52935c79f4f91e0cc7189b0170466d7f8002569cbe2e2c7661f.0 origin refspec: 62f27eb28b9fd52935c79f4f91e0cc7189b0170466d7f8002569cbe2e2c7661f
# ostree admin status * torizon e3352d041d1e52a3c6bd7aa1c4247c3e46e07e4eb9a902b457fe778f8250eb84.0 origin refspec: toradex-nightly:apalis-imx6/torizon/torizon-core-podman torizon 62f27eb28b9fd52935c79f4f91e0cc7189b0170466d7f8002569cbe2e2c7661f.0 (rollback) origin refspec: 62f27eb28b9fd52935c79f4f91e0cc7189b0170466d7f8002569cbe2e2c7661f
If you are building TorizonCore image locally you may provide an ostree repo directly from your PC. If you have Python installed, just move to the ostree_repo folder of your build directory (should be under deploy/images/$MACHINE/ostree_repo) and bring-up the Python built-in simple HTTP server:
$ python -m SimpleHTTPServer 8081
In this way your PC will be sharing the image you just built on port 8081. You can replace http://feeds.toradex.com/ostree/nightly/apalis-imx6/ in the above instructions with
<your PC ip address>:8081 and update your device directly from your build machine.
Please notice that this kind of operation is not secure and such a configuration should be used only for debugging purposes.
If you don't have network connectivity on target board, In that case, copy the OStree repo to the USB thumb drive then connect the USB thumb drive to the target board and then one can do the update by following the instructions below.
If you are building TorizonCore image locally the OSTree files will be in deploy/images/$MACHINE/ostree_repo.
# ostree refs --repo=PATH_TO_REPO_DIRCTORY
# ostree refs --repo=/home/root/pendrive/ostree_repo/ apalis-imx6/torizon/torizon-core-docker apalis-imx6/torizon/torizon-core-docker-torizon-core-docker
# ostree pull-local PATH_TO_USB_REPO REFS_NAME
# ostree pull-local /home/root/pendrive/ostree_repo/ apalis-imx6/torizon/torizon-core-docker
# ostree admin deploy REFS
e.g. ostree admin deploy apalis-imx6/torizon/torizon-core-docker
# ostree admin status torizon 1d98e25015a390556e7ab93c9b94e01e8632d30d800b36bff1ddd54fa9fc7cf4.0 (pending) origin refspec: apalis-imx6/torizon/torizon-core-docker * torizon d0d53487d305358ad50c37b1b2a94fc78eaea5e770749a33f5607573e2447660.0 origin refspec: d0d53487d305358ad50c37b1b2a94fc78eaea5e770749a33f5607573e2447660
Finally, you can view your current and previous deployment which you can rollback to if need be.
# ostree admin status * torizon 1d98e25015a390556e7ab93c9b94e01e8632d30d800b36bff1ddd54fa9fc7cf4.0 origin refspec: apalis-imx6/torizon/torizon-core-docker torizon d0d53487d305358ad50c37b1b2a94fc78eaea5e770749a33f5607573e2447660.0 (rollback) origin refspec: d0d53487d305358ad50c37b1b2a94fc78eaea5e770749a33f5607573e2447660