.\" Man page generated from reStructuredText. . .TH "SWUPDATE" "1" "Jan 19, 2021" "2020.11" "Embedded Software Update Documentation" .SH NAME swupdate \- Swupdate Documentation . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. [image] .sp SWUpdate provides a reliable way to update the software on an embedded system. Sources are hosted at \fI\%https://github.com/sbabic/swupdate\fP .SH SOFTWARE MANAGEMENT ON EMBEDDED SYSTEMS .sp Embedded Systems become more and more complex, and their software reflects the augmented complexity. New features and fixes let much more as desirable that the software on an embedded system can be updated in an absolutely reliable way. .sp On a Linux\-based system, we can find in most cases the following elements: .INDENT 0.0 .IP \(bu 2 the boot loader. .IP \(bu 2 the kernel and the DT (Device Tree) file. .IP \(bu 2 the root file system .IP \(bu 2 other file systems, mounted at a later point .IP \(bu 2 customer data, in raw format or on a file system .IP \(bu 2 application specific software. For example, firmware to be downloaded on connected micro\-controllers, and so on. .UNINDENT .sp Generally speaking, in most cases it is required to update kernel and root file system, preserving user data \- but cases vary. .sp In only a few cases it is required to update the boot loader, too. In fact, updating the boot loader is quite always risky, because a failure in the update breaks the board. Restoring a broken board is possible in some cases, but this is not left in most cases to the end user and the system must be sent back to the manufacturer. .sp There are a lot of different concepts about updating the software. I like to expose some of them, and then explain why I have implemented this project. .SS Updating through the boot loader .sp Boot loaders do much more as simply start the kernel. They have their own shell and can be managed using a processor\(aqs peripheral, in most cases a serial line. They are often script\-able, letting possible to implement some kind of software update mechanism. .sp However, I found some drawbacks in this approach, that let me search for another solution, based on an application running on Linux: .SS Boot loaders have limited access to peripherals .sp Not all peripherals supported by the kernel are available with the boot loader. When it makes sense to add support to the kernel, because the peripheral is then available by the main application, it does not always make sense to duplicate the effort to port the driver to the boot loader. .SS Boot loader\(aqs drivers are not updated .sp Boot loader\(aqs drivers are mostly ported from the Linux kernel, but due to adaptations they are not later fixed or synchronized with the kernel, while bug fixes flow regularly in the Linux kernel. Some peripherals can then work in a not reliable ways, and fixing the issues can be not easy. Drivers in boot loaders are more or less a fork of the respective drivers in kernel. .sp As example, the UBI / UBIFS for NAND devices contains a lot of fixes in the kernel, that are not ported back to the boot loaders. The same can be found for the USB stack. The effort to support new peripherals or protocols is better to be used for the kernel as for the boot loaders. .SS Reduced file systems .sp The number of supported file systems is limited and porting a file system to the boot loader requires high effort. .SS Network support is limited .sp Network stack is limited, generally an update is possible via UDP but not via TCP. .SS Interaction with the operator .sp It is difficult to expose an interface to the operator, such as a GUI with a browser or on a display. .sp A complex logic can be easier implemented inside an application else in the boot loader. Extending the boot loader becomes complicated because the whole range of services and libraries are not available. .SS Boot loader\(aqs update advantages .sp However, this approach has some advantages, too: .INDENT 0.0 .IP \(bu 2 software for update is generally simpler. \- smaller footprint: a stand\-alone application only for software management requires an own kernel and a root file system. Even if their size can be trimmed dropping what is not required for updating the software, their size is not negligible. .UNINDENT .SS Updating through a package manager .sp All Linux distributions are updating with a package manager. Why is it not suitable for embedded ? .sp I cannot say it cannot be used, but there is an important drawback using this approach. Embedded systems are well tested with a specific software. Using a package manager can put weirdness because the software itself is not anymore \fIatomic\fP, but split into a long list of packages. How can we be assured that an application with library version x.y works, and also with different versions of the same library? How can it be successfully tested? .sp For a manufacturer, it is generally better to say that a new release of software (well tested by its test engineers) is released, and the new software (or firmware) is available for updating. Splitting in packages can generate nightmare and high effort for the testers. .sp The ease of replacing single files can speed up the development, but it is a software\-versions nightmare at the customer site. If a customer report a bug, how can it is possible that software is "version 2.5" when a patch for some files were sent previously to the customer ? .sp An atomic update is generally a must feature for an embedded system. .SS Strategies for an application doing software upgrade .sp Instead of using the boot loader, an application can take into charge to upgrade the system. The application can use all services provided by the OS. The proposed solution is a stand\-alone software, that follow customer rules and performs checks to determine if a software is installable, and then install the software on the desired storage. .sp The application can detect if the provided new software is suitable for the hardware, and it is can also check if the software is released by a verified authority. The range of features can grow from small system to a complex one, including the possibility to have pre\- and post\- install scripts, and so on. .sp Different strategies can be used, depending on the system\(aqs resources. I am listing some of them. .SS Double copy with fall\-back .sp If there is enough space on the storage to save two copies of the whole software, it is possible to guarantee that there is always a working copy even if the software update is interrupted or a power off occurs. .sp Each copy must contain the kernel, the root file system, and each further component that can be updated. It is required a mechanism to identify which version is running. .sp SWUpdate should be inserted in the application software, and the application software will trigger it when an update is required. The duty of SWUpdate is to update the stand\-by copy, leaving the running copy of the software untouched. .sp A synergy with the boot loader is often necessary, because the boot loader must decide which copy should be started. Again, it must be possible to switch between the two copies. After a reboot, the boot loader decides which copy should run. [image] .sp Check the chapter about boot loader to see which mechanisms can be implemented to guarantee that the target is not broken after an update. .sp The most evident drawback is the amount of required space. The available space for each copy is less than half the size of the storage. However, an update is always safe even in case of power off. .sp This project supports this strategy. The application as part of this project should be installed in the root file system and started or triggered as required. There is no need of an own kernel, because the two copies guarantees that it is always possible to upgrade the not running copy. .sp SWUpdate will set bootloader\(aqs variable to signal the that a new image is successfully installed. .SS Single copy \- running as standalone image .sp The software upgrade application consists of kernel (maybe reduced dropping not required drivers) and a small root file system, with the application and its libraries. The whole size is much less than a single copy of the system software. Depending on set up, I get sizes from 2.5 until 8 MB for the stand\-alone root file system. If the size is very important on small systems, it becomes negligible on systems with a lot of storage or big NANDs. .sp The system can be put in "upgrade" mode, simply signaling to the boot loader that the upgrading software must be started. The way can differ, for example setting a boot loader environment or using and external GPIO. .sp The boot loader starts "SWUpdate", booting the SWUpdate kernel and the initrd image as root file system. Because it runs in RAM, it is possible to upgrade the whole storage. Differently as in the double\-copy strategy, the systems must reboot to put itself in update mode. .sp This concept consumes less space in storage as having two copies, but it does not guarantee a fall\-back without updating again the software. However, it can be guaranteed that the system goes automatically in upgrade mode when the productivity software is not found or corrupted, as well as when the upgrade process is interrupted for some reason. [image] .sp In fact, it is possible to consider the upgrade procedure as a transaction, and only after the successful upgrade the new software is set as "boot\-able". With these considerations, an upgrade with this strategy is safe: it is always guaranteed that the system boots and it is ready to get a new software, if the old one is corrupted or cannot run. With U\-Boot as boot loader, SWUpdate is able to manage U\-Boot\(aqs environment setting variables to indicate the start and the end of a transaction and that the storage contains a valid software. A similar feature for GRUB environment block modification as well as for EFI Boot Guard has been introduced. .sp SWUpdate is mainly used in this configuration. The recipes for Yocto generate an initrd image containing the SWUpdate application, that is automatically started after mounting the root file system. [image] .SS Something went wrong ? .sp Many things can go wrong, and it must be guaranteed that the system is able to run again and maybe able to reload a new software to fix a damaged image. SWUpdate works together with the boot loader to identify the possible causes of failures. Currently U\-Boot, GRUB, and EFI Boot Guard are supported. .sp We can at least group some of the common causes: .INDENT 0.0 .IP \(bu 2 damage / corrupted image during installing. SWUpdate is able to recognize it and the update process is interrupted. The old software is preserved and nothing is really copied into the target\(aqs storage. .IP \(bu 2 corrupted image in the storage (flash) .IP \(bu 2 remote update interrupted due to communication problem. .IP \(bu 2 power\-failure .UNINDENT .sp SWUpdate works as transaction process. The boot loader environment variable "recovery_status" is set to signal the update\(aqs status to the boot loader. Of course, further variables can be added to fine tuning and report error causes. recovery_status can have the values "progress", "failed", or it can be unset. .sp When SWUpdate starts, it sets recovery_status to "progress". After an update is finished with success, the variable is erased. If the update ends with an error, recovery_status has the value "failed". .sp When an update is interrupted, independently from the cause, the boot loader recognizes it because the recovery_status variable is in "progress" or "failed". The boot loader can then start again SWUpdate to load again the software (single\-copy case) or run the old copy of the application (double\-copy case). .SS Power Failure .sp If a power off occurs, it must be guaranteed that the system is able to work again \- starting again SWUpdate or restoring an old copy of the software. .sp Generally, the behavior can be split according to the chosen scenario: .INDENT 0.0 .IP \(bu 2 single copy: SWUpdate is interrupted and the update transaction did not end with a success. The boot loader is able to start SWUpdate again, having the possibility to update the software again. .IP \(bu 2 double copy: SWUpdate did not switch between stand\-by and current copy. The same version of software, that was not touched by the update, is started again. .UNINDENT .sp To be completely safe, SWUpdate and the bootloader need to exchange some information. The bootloader must detect if an update was interrupted due to a power\-off, and restart SWUpdate until an update is successful. SWUpdate supports the U\-Boot, GRUB, and EFI Boot Guard bootloaders. U\-Boot and EFI Boot Guard have a power\-safe environment which SWUpdate is able to read and change in order to communicate with them. In case of GRUB, a fixed 1024\-byte environment block file is used instead. SWUpdate sets a variable as flag when it starts to update the system and resets the same variable after completion. The bootloader can read this flag to check if an update was running before a power\-off. [image] .SS What about upgrading SWUpdate itself ? .sp SWUpdate is thought to be used in the whole development process, replacing customized process to update the software during the development. Before going into production, SWUpdate is well tested for a project. .sp If SWUpdate itself should be updated, the update cannot be safe if there is only one copy of SWUpdate in the storage. Safe update can be guaranteed only if SWUpdate is duplicated. .sp There are some ways to circumvent this issue if SWUpdate is part of the upgraded image: .INDENT 0.0 .IP \(bu 2 have two copies of SWUpdate .IP \(bu 2 take the risk, but have a rescue procedure using the boot loader. .UNINDENT .SS What about upgrading the Boot loader ? .sp Updating the boot loader is in most cases a one\-way process. On most SOCs, there is no possibility to have multiple copies of the boot loader, and when boot loader is broken, the board does not simply boot. .sp Some SOCs allow one to have multiple copies of the boot loader. But again, there is no general solution for this because it is \fIvery\fP hardware specific. .sp In my experience, most targets do not allow one to update the boot loader. It is very uncommon that the boot loader must be updated when the product is ready for production. .sp It is different if the U\-Boot environment must be updated, that is a common practice. U\-Boot provides a double copy of the whole environment, and updating the environment from SWUpdate is power\-off safe. Other boot loaders can or cannot have this feature. .SH LICENSE .sp SWUpdate is Free Software. It is copyrighted by Stefano Babic and many others who contributed code (see the actual source code and the git commit messages for details). You can redistribute SWUpdate and/or modify it under the terms of version 2 of the GNU General Public License as published by the Free Software Foundation. Most of it can also be distributed, at your option, under any later version of the GNU General Public License \-\- see individual files for exceptions. .sp To make this easier, license headers in the source files will be replaced with a single line reference to Unique License Identifiers as defined by the Linux Foundation\(aqs SPDX project [1]. For example, in a source file the full "GPL v2.0 or later" header text will be replaced by a single line: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C SPDX\-License\-Identifier: GPL\-2.0+ .ft P .fi .UNINDENT .UNINDENT .sp Ideally, the license terms of all files in the source tree should be defined by such License Identifiers; in no case a file can contain more than one such License Identifier list. .sp If a "SPDX\-License\-Identifier:" line references more than one Unique License Identifier, then this means that the respective file can be used under the terms of either of these licenses, i. e. with .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C SPDX\-License\-Identifier: GPL\-2.0+ BSD\-3\-Clause .ft P .fi .UNINDENT .UNINDENT .sp you can choose between GPL\-2.0+ and BSD\-3\-Clause licensing. .sp We use the \fI\%SPDX\fP Unique License Identifiers (\fI\%SPDX\-Identifiers\fP) .SH LICENSES .TS center; |l|l|l|. _ T{ Full name T} T{ SPDX Identifier T} T{ OSI Approved T} _ T{ GNU General Public License \fI\%v2.0\fP only T} T{ GPL\-2.0\-only T} T{ Y T} _ T{ GNU General Public License \fI\%v2.0\fP or later T} T{ GPL\-2.0\-or\-later T} T{ Y T} _ T{ GNU Lesser General Public License \fI\%v2.1\fP or later T} T{ LGPL\-2.1\-or\-later T} T{ Y T} _ T{ BSD \fI\%2\-Clause\fP License T} T{ BSD\-2\-Clause T} T{ Y T} _ T{ BSD \fI\%3\-clause\fP "New" or "Revised" License T} T{ BSD\-3\-Clause T} T{ Y T} _ T{ \fI\%MIT\fP License T} T{ MIT T} T{ Y T} _ .TE .SH SWUPDATE: SOFTWARE UPDATE FOR EMBEDDED SYSTEM .SS Overview .sp This project is thought to help to update an embedded system from a storage media or from network. However, it should be mainly considered as a framework, where further protocols or installers (in SWUpdate they are called handlers) can be easily added to the application. .sp One use case is to update from an external local media, as USB\-Pen or SD\-Card. In this case, the update is done without any intervention by an operator: it is thought as "one\-key\-update", and the software is started at reset simply pressing a key (or in any way that can be recognized by the target), making all checks automatically. At the end, the updating process reports only the status to the operator (successful or failed). .sp The output can be displayed on a LCD using the frame\-buffer device or directed to a serial line (Linux console). .sp It is generally used in the single copy approach, running in an initrd (recipes are provided to generate with Yocto). However, it is possible to use it in a double\-copy approach by use of collections\&. .sp If started for a remote update, SWUpdate starts an embedded Web\-server and waits for requests. The operator must upload a suitable image, that SWUpdate checks and then install. All output is notified to the operator\(aqs browser via AJAX notifications. .SS Features .SS General Overview .INDENT 0.0 .IP \(bu 2 Install on embedded Media (eMMC, SD, Raw NAND, NOR and SPI\-NOR flashes) .IP \(bu 2 check if an image is available. The image is built in a specified format (cpio) and it must contain a file describing the software that must be updated. .IP \(bu 2 SWUpdate is thought to update UBI volumes (mainly for NAND, but not only) and images on devices. Passing a whole image can still be updated as a partition on the SD card, or a MTD partition. .IP \(bu 2 new partition schema. This is bound with UBI volume. SWUpdate can recreate UBI volumes, resizing them and copying the new software. .IP \(bu 2 support for compressed images, using the zlib and zstd library. tarball (tgz file) are supported. .IP \(bu 2 support for partitioned USB\-pen or unpartitioned (mainly used by Windows). .IP \(bu 2 support for updating a single file inside a filesystem. The filesystem where to put the file must be described. .IP \(bu 2 checksum for the single components of an image .IP \(bu 2 use a structured language to describe the image. This is done using the \fI\%libconfig\fP library as default parser, that uses a JSON\-like description. .IP \(bu 2 use custom\(aqs choice for the description of the image. It is possible to write an own parser using the Lua language. An example using a XML description in Lua is provided in the examples directory. .IP \(bu 2 Support for setting / erasing U\-Boot variables .IP \(bu 2 Support for setting / erasing \fI\%GRUB\fP environment block variables .IP \(bu 2 Support for setting / erasing \fI\%EFI Boot Guard\fP variables .IP \(bu 2 Support for preinstall scripts. They run before updating the images .IP \(bu 2 Support for postinstall scripts. They run after updating the images. .IP \(bu 2 Network installer using an embedded Web\-server (Mongoose Server was chosen, in the version under Lua license). A different Web\-server can be used. .IP \(bu 2 .INDENT 2.0 .TP .B Multiple interfaces for getting software .INDENT 7.0 .IP \(bu 2 local Storage: USB, SD, UART,.. .UNINDENT .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B OTA / Remote .INDENT 7.0 .IP \(bu 2 integrated Web\-Server .IP \(bu 2 pulling from remote Server (HTTP, HTTPS, ..) .IP \(bu 2 using a Backend. SWUpdate is open to talk with back end servers for rolling out software updates. Current version supports the hawkBit server, but other backend can be added. .UNINDENT .UNINDENT .IP \(bu 2 Can be configured to check for compatibility between software and hardware revisions. The software image must contain an entry declaring on which HW revision the software is allowed to run. SWUpdate refuses to install if the compatibility is not verified. .IP \(bu 2 support for image extraction. A manufacturer can require to have a single image that contains the software for more as one device. This simplifies the manufacturer\(aqs management and reduces their administrative costs having a single software product. SWUpdate receives the software as stream without temporary storing, and extracts only the required components for the device to be installed. .IP \(bu 2 allow custom handlers for installing FPGA firmware, micro\-controller firmware via custom protocols. .IP \(bu 2 Features are enabled / disabled using "make menuconfig". (Kbuild is inherited from busybox project) .IP \(bu 2 Images are authenticated and verified before installing .IP \(bu 2 Power\-Off safe .UNINDENT .SS Single image delivery .sp The main concept is that the manufacturer delivers a single big image. All single images are packed together (cpio was chosen for its simplicity and because can be streamed) together with an additional file (sw\-description), that contains meta information about each single image. .sp The format of sw\-description can be customized: SWUpdate can be configured to use its internal parser (based on libconfig), or calling an external parser in Lua. [image] .sp Changing the rules to accept images with an external parser, let to extend to new image types and how they are installed. In fact, the scope of the parser is to retrieve which single images must be installed and how. SWUpdate implements "handlers" to install a single image: there are handlers to install images into UBI volumes, or to a SD card, a CFI Flash, and so on. It is then easy to add an own handler if a very special installer is required. .sp For example we can think at a project with a main processor and one or several micro\-controllers. Let\(aqs say for simplicity that the main processor communicates with the micro\-controllers via UARTS using a proprietary protocol. The software on the micro\-controllers can be updated using the proprietary protocol. .sp It is possible to extend SWUpdate writing a handler, that implements the part of the proprietary protocol to perform the upgrade on the micro\-controller. The parser must recognize which image must be installed with the new handler, and SWUpdate will call the handler during the installation process. .SS Streaming feature .sp SWUpdate is thought to be able to stream the received image directly into the target, without any temporary copy. In fact, the single installer (handler) receive as input the file descriptor set at the beginning of the image that must be installed. .sp The feature can be set on image basis, that means that a user can decide which partial images should be streamed. If not streamed (see installed\-directly flag), files are temporary extracted into the directory pointed to by the environment variable \fBTMPDIR\fP with \fB/tmp\fP as fall\-back if \fBTMPDIR\fP is not set. Of course, by streaming it is not possible to make checks on the whole delivered software before installing. The temporary copy is done only when updated from network. When the image is stored on an external storage, there is no need of that copy. .SS Images fully streamed .sp In case of remote update, SWUpdate extracts relevant images from the stream and copies them into the directory pointed to by the environment variable \fBTMPDIR\fP (if unset, to \fB/tmp\fP) before calling the handlers. This guarantee that an update is initiated only if all parts are present and correct. However, on some systems with less resources, the amount of RAM to copy the images could be not enough, for example if the filesystem on an attached SD Card must be updated. In this case, it will help if the images are installed directly as stream by the corresponding handler, without temporary copies. Not all handlers support to stream directly into the target. Streaming with zero\-copy is enabled by setting the flag "installed\-directly" in the description of the single image. .SS Configuration and build .SS Requirements .sp There are only a few libraries that are required to compile SWUpdate. .INDENT 0.0 .IP \(bu 2 mtd\-utils: internally, mtd\-utils generates libmtd and libubi. They are commonly not exported and not installed, but they are linked by SWUpdate to reuse the same functions for upgrading MTD and UBI volumes. .IP \(bu 2 openssl / wolfssl / mbedtls (optional) for cryptographic operations .IP \(bu 2 p11\-kit & wolfssl (optional) for PKCS#11 support .IP \(bu 2 Lua: liblua and the development headers. .IP \(bu 2 libz is always linked. .IP \(bu 2 libconfig (optional) for the default parser .IP \(bu 2 libarchive (optional) for archive handler .IP \(bu 2 librsync (optional) for support to apply rdiff patches .IP \(bu 2 libjson (optional) for JSON parser and hawkBit .IP \(bu 2 libubootenv (optional) if support for U\-Boot is enabled .IP \(bu 2 libebgenv (optional) if support for EFI Boot Guard is enabled .IP \(bu 2 libcurl used to communicate with network .UNINDENT .sp New handlers can add some other libraries to the requirement list \- check if you need all handlers in case you get build errors, and drop what you do not need. .SS Building with Yocto .sp See corresponding chapter how to build in Yocto. .SS Configuring SWUpdate .sp SWUpdate is configurable via "make menuconfig". The small footprint is reached using the internal parser and disabling the web server. Any option has a small help describing its usage. In the default configuration, many options are already activated. .sp To configure the options: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C make menuconfig .ft P .fi .UNINDENT .UNINDENT .SS Building .INDENT 0.0 .IP \(bu 2 to cross\-compile, set the CC and CXX variables before running make. It is also possible to set the cross\-compiler prefix as option with make menuconfig. .IP \(bu 2 generate the code .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C make .ft P .fi .UNINDENT .UNINDENT .sp The result is the binary "swupdate". A second binary "progress" is built, but it is not strictly required. It is an example how to build your own interface to SWUpdate to show a progress bar or whatever you want on your HMI. The example simply prints on the console the current status of the update. .sp In the Yocto buildsystem,: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C bitbake swupdate .ft P .fi .UNINDENT .UNINDENT .sp This will build the package .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C bitbake swupdate\-image .ft P .fi .UNINDENT .UNINDENT .sp This builds a rescue image. The result is a Ramdisk that can be loaded directly by the bootloader. To use SWUpdate in the double\-copy mode, put the package swupdate into your rootfs. Check your image recipe, and simply add it to the list of the installed packages. .sp For example, if we want to add it to the standard "core\-image\-full\-cmdline" image, we can add a \fIrecipes\-extended/images/core\-image\-full\-cmdline.bbappend\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C IMAGE_INSTALL += " \e swupdate \e swupdate\-www \e " .ft P .fi .UNINDENT .UNINDENT .sp swupdate\-www is the package with the website, that you can customize with your own logo, template ans style. .SS Building a debian package .sp SWUpdate is thought for Embedded Systems and building in an embedded distribution is the first use case. But apart the most used buildsystems for embedded as Yocto or Buildroot, in some cases a standard Linux distro is used. Not only, a distro package allows one to run SWUpdate on Linux PC for test purposes without having to fight with dependencies. Using the debhelper tools, it is possible to generate a debian package. .SS Steps for building a debian package .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \&./debian/rules clean \&./debian/rules build fakeroot debian/rules binary .ft P .fi .UNINDENT .UNINDENT .sp The result is a "deb" package stored in the parent directory. .SS Alternative way signing source package .sp You can use dpkg\-buildpackage: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C dpkg\-buildpackage \-us \-uc debsign \-k .ft P .fi .UNINDENT .UNINDENT .SS Running SWUpdate .SS What is expected from a SWUpdate run .sp A run of SWUpdate consists mainly of the following steps: .INDENT 0.0 .IP \(bu 2 check for media (USB\-pen) .IP \(bu 2 check for an image file. The extension must be .swu .IP \(bu 2 extracts sw\-description from the image and verifies it It parses sw\-description creating a raw description in RAM about the activities that must be performed. .IP \(bu 2 Reads the cpio archive and proofs the checksum of each single file SWUpdate stops if the archive is not complete verified .IP \(bu 2 check for hardware\-software compatibility, if any, reading hardware revision from hardware and matching with the table in sw\-description. .IP \(bu 2 check that all components described in sw\-description are really in the cpio archive. .IP \(bu 2 modify partitions, if required. This consists in a resize of UBI volumes, not a resize of MTD partition. .IP \(bu 2 runs pre\-install scripts .IP \(bu 2 iterates through all images and call the corresponding handler for installing on target. .IP \(bu 2 runs post\-install scripts .IP \(bu 2 update bootloader environment, if changes are specified in sw\-description. .IP \(bu 2 reports the status to the operator (stdout) .UNINDENT .sp The first step that fails, stops the entire procedure and an error is reported. .sp To start SWUpdate expecting the image from a file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C swupdate \-i .ft P .fi .UNINDENT .UNINDENT .sp To start with the embedded web server: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C swupdate \-w "" .ft P .fi .UNINDENT .UNINDENT .sp The main important parameters for the web server are "document\-root" and "port". .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C swupdate \-w "\-\-document\-root ./www \-\-port 8080" .ft P .fi .UNINDENT .UNINDENT .sp The embedded web server is taken from the Mongoose project. .sp The list of available options (depending on activated features) is shown with: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C swupdate \-h .ft P .fi .UNINDENT .UNINDENT .sp This uses as website the pages delivered with the code. Of course, they can be customized and replaced. The website uses AJAX to communicate with SWUpdate, and to show the progress of the update to the operator. .sp The default port of the Web\-server is 8080. You can then connect to the target with: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C http://:8080 .ft P .fi .UNINDENT .UNINDENT .sp If it works, the start page should be displayed as in next figure. [image] .sp If a correct image is downloaded, SWUpdate starts to process the received image. All notifications are sent back to the browser. SWUpdate provides a mechanism to send to a receiver the progress of the installation. In fact, SWUpdate takes a list of objects that registers itself with the application and they will be informed any time the application calls the notify() function. This allows also for self\-written handlers to inform the upper layers about error conditions or simply return the status. It is then simply to add own receivers to implement customized way to display the results: displaying on a LCD (if the target has one), or sending back to another device via network. An example of the notifications sent back to the browser is in the next figure: [image] .sp Software collections can be specified by passing \fI\-\-select\fP command line option. Assuming \fIsw\-description\fP file contains a collection named \fIstable\fP, with \fIalt\fP installation location, \fISWUpdate\fP can be called like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C swupdate \-\-select stable,alt .ft P .fi .UNINDENT .UNINDENT .SS Command line parameters .TS center; |l|l|l|. _ T{ Parameter T} T{ Type T} T{ Description T} _ T{ \-f T} T{ string T} T{ SWUpdate configuration file to use. See \fBexamples/configuration/swupdate.cfg\fP in the source code for details. T} _ T{ \-b T} T{ string T} T{ Available if CONFIG_UBIATTACH is set. It allows one to blacklist MTDs when SWUpdate searches for UBI volumes. Example: U\-Boot and environment in MTD0\-1: \fBswupdate \-b "0 1"\fP\&. T} _ T{ \-e T} T{ string T} T{ \fBsel\fP is in the format ,. It allows one to find a subset of rules in the sw\-description file. With it, multiple rules are allowed. One common usage is in case of the dual copy approach. Example: \-e "stable, copy1" ==> install on copy1 \-e "stable, copy2" ==> install on copy2 T} _ T{ .INDENT 0.0 .TP .B \-\-excluded .UNINDENT T} T{ string T} T{ \fBsel\fP is in the format ,. It sets a blacklist of selections that cannot be used for an update. Selections can be activated not only with \-e, but also via IPC. Multiple \-\-excluded are allowed T} _ T{ \-h T} T{ .INDENT 0.0 .IP \(bu 2 .UNINDENT T} T{ Run usage with help. T} _ T{ \-k T} T{ string T} T{ Available if CONFIG_SIGNED is set. Filename with the public key. T} _ T{ \-K T} T{ string T} T{ Available on CONFIG_ENCRYPTED_IMAGES set. Filename with the symmetric key to be used for decryption. T} _ T{ \-\-cert\-purpose T} T{ string T} T{ Available if CONFIG_SIGNED_IMAGES is set. Set expected certificate purpose. T} _ T{ \-\-forced\-signer\-name T} T{ string T} T{ Available if CONFIG_SIGNED_IMAGES is set. Set expected common name of signer certificate. T} _ T{ \-\-ca\-path T} T{ string T} T{ Available if CONFIG_SIGNED_IMAGES is set. Path to the Certificate Authority (PEM). T} _ T{ \-l T} T{ int T} T{ Set loglevel. T} _ T{ \-L T} T{ .INDENT 0.0 .IP \(bu 2 .UNINDENT T} T{ Send LOG output to syslog (local). T} _ T{ \-i T} T{ string T} T{ Run SWUpdate with a local .swu file. T} _ T{ \-n T} T{ .INDENT 0.0 .IP \(bu 2 .UNINDENT T} T{ Run SWUpdate in dry\-run mode. T} _ T{ \-N T} T{ string T} T{ The minimum required version of software. This will be checked with the version of new software and forbids downgrading. Version consists of either 4 numbers (major.minor.rev.build with each field in the range 0..65535) or it is a semantic version. T} _ T{ \-R T} T{ string T} T{ The current installed version of software. This will be checked with the version of new software and forbids reinstalling. T} _ T{ \-o T} T{ string T} T{ Save the stream (SWU) to a file. T} _ T{ \-v T} T{ .INDENT 0.0 .IP \(bu 2 .UNINDENT T} T{ Activate verbose output. T} _ T{ \-M T} T{ .INDENT 0.0 .IP \(bu 2 .UNINDENT T} T{ Disable setting the bootloader transaction marker. T} _ T{ \-w T} T{ string T} T{ Available if CONFIG_WEBSERVER is set. Start internal webserver and pass to it a command line string. T} _ T{ \-d T} T{ string T} T{ Available if CONFIG_DOWNLOAD is set. Start internal downloader client and pass to it a command line string. See below the internal command line arguments for the downloader. T} _ T{ \-u T} T{ string T} T{ Available if CONFIG_SURICATTA is set. Start internal suricatta client daemon and pass to it a command line string. See below the internal command line arguments for suricatta. T} _ T{ \-H T} T{ string T} T{ Available on CONFIG_HW_COMPATIBILITY set. Set board name and hardware revision. T} _ T{ \-c T} T{ .INDENT 0.0 .IP \(bu 2 .UNINDENT T} T{ Check \fB*.swu\fP file. It ensures that files referenced in sw\-description are present. Usage: \fBswupdate \-c \-i \fP T} _ T{ \-P T} T{ string T} T{ Execute pre\-update command. T} _ T{ \-p T} T{ string T} T{ Execute post\-update command. T} _ .TE .SS Downloader command line parameters .sp Example: \fBswupdate \-d "\-u example.com"\fP .sp Mandatory arguments are marked with \(aq*\(aq: .TS center; |l|l|l|. _ T{ Parameter T} T{ Type T} T{ Description T} _ T{ \-u T} T{ string T} T{ * This is the URL where new software is pulled. URL is a link to a valid .swu image T} _ T{ \-r T} T{ integer T} T{ Number of retries before a download is considered broken. With "\-r 0", SWUpdate will not stop until a valid software is loaded. T} _ T{ \-t T} T{ integer T} T{ Timeout for connection lost downloader or Webserver T} _ T{ \-a T} T{ string T} T{ Send user and password for Basic Auth T} _ .TE .SS Suricatta command line parameters .sp Example: \fBswupdate \-u "\-t default \-u localhost:8080 \-i 1B7"\fP .sp Note that different suricatta modules may have different parameters. The below listed options are for SWUpdate\(aqs hawkBit support. .sp Mandatory arguments are marked with \(aq*\(aq: .TS center; |l|l|l|. _ T{ Parameter T} T{ Type T} T{ Description T} _ T{ \-t T} T{ string T} T{ * Set hawkBit tenant ID for this device. T} _ T{ \-u T} T{ string T} T{ * Host and port of the hawkBit instance, e.g., localhost:8080 T} _ T{ \-i T} T{ integer T} T{ * The device ID to communicate to hawkBit. T} _ T{ \-c T} T{ integer T} T{ Confirm update status to server: 1=AGAIN, 2=SUCCESS, 3=FAILED T} _ T{ \-x T} T{ .INDENT 0.0 .IP \(bu 2 .UNINDENT T} T{ Do not abort on flawed server certificates. T} _ T{ \-p T} T{ integer T} T{ Delay in seconds between two hawkBit poll operations (default: 45s). T} _ T{ \-r T} T{ integer T} T{ Resume and retry interrupted downloads (default: 5 tries). T} _ T{ \-w T} T{ integer T} T{ Time to wait prior to retry and resume a download (default: 5s). T} _ T{ \-y T} T{ string T} T{ Use proxy. Either give proxy URL, else {http,all}_proxy env is tried. T} _ T{ \-k T} T{ string T} T{ Set target token. T} _ T{ \-g T} T{ string T} T{ Set gateway token. T} _ T{ \-f T} T{ string T} T{ Set the network interface to connect to hawkBit. T} _ T{ \-e T} T{ .INDENT 0.0 .IP \(bu 2 .UNINDENT T} T{ Daemon enabled at startup (default). T} _ T{ \-d T} T{ .INDENT 0.0 .IP \(bu 2 .UNINDENT T} T{ Daemon disabled at startup. T} _ T{ \-\-disable\-token\-for\-dwl T} T{ .INDENT 0.0 .IP \(bu 2 .UNINDENT T} T{ Do not send authentication header when downloading SWU. T} _ T{ \-\-cache\-file T} T{ string T} T{ This allow to resume an update after a power cut. If the SWU is saved in a file, SWUpdate can reuse the file and download just the remaining part of the SWU. T} _ .TE .SS systemd Integration .sp SWUpdate has optional \fI\%systemd\fP support via the compile\-time configuration switch \fBCONFIG_SYSTEMD\fP\&. If enabled, SWUpdate signals systemd about start\-up completion and can make optional use of systemd\(aqs socket\-based activation feature. .sp A sample systemd service unit file \fB/etc/systemd/system/swupdate.service\fP may look like the following starting SWUpdate in suricatta daemon mode: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [Unit] Description=SWUpdate daemon Documentation=https://github.com/sbabic/swupdate Documentation=https://sbabic.github.io/swupdate [Service] Type=notify ExecStart=/usr/bin/swupdate \-u \(aq\-t default \-u http://localhost \-i 25\(aq [Install] WantedBy=multi\-user.target .ft P .fi .UNINDENT .UNINDENT .sp Started via \fBsystemctl start swupdate.service\fP, SWUpdate (re)creates its sockets on startup. For using socket\-based activation, an accompanying systemd socket unit file \fB/etc/systemd/system/swupdate.socket\fP is required: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [Unit] Description=SWUpdate socket listener Documentation=https://github.com/sbabic/swupdate Documentation=https://sbabic.github.io/swupdate [Socket] ListenStream=/tmp/sockinstctrl ListenStream=/tmp/swupdateprog [Install] WantedBy=sockets.target .ft P .fi .UNINDENT .UNINDENT .sp On \fBswupdate.socket\fP being started, systemd creates the socket files and hands them over to SWUpdate when it starts. So, for example, when talking to \fB/tmp/swupdateprog\fP, systemd starts \fBswupdate.service\fP and hands\-over the socket files. The socket files are also handed over on a "regular" start of SWUpdate via \fBsystemctl start swupdate.service\fP\&. .sp Note that the socket paths in the two \fBListenStream=\fP directives have to match the socket paths \fBCONFIG_SOCKET_CTRL_PATH\fP and \fBCONFIG_SOCKET_PROGRESS_PATH\fP in SWUpdate\(aqs configuration. Here, the default socket path configuration is depicted. .SS Changes in boot\-loader code .sp The SWUpdate consists of kernel and a root filesystem (image) that must be started by the boot\-loader. In case using U\-Boot, the following mechanism can be implemented: .INDENT 0.0 .IP \(bu 2 U\-Boot checks if a sw update is required (check gpio, serial console, etc.). .IP \(bu 2 the script "altbootcmd" sets the rules to start SWUpdate .IP \(bu 2 in case SWUpdate is required, U\-boot run the script "altbootcmd" .UNINDENT .sp Is it safe to change U\-Boot environment ? Well, it is, but U\-Boot must be configured correctly. U\-Boot supports two copies of the environment to be power\-off safe during an environment update. The board\(aqs configuration file must have defined CONFIG_ENV_OFFSET_REDUND or CONFIG_ENV_ADDR_REDUND. Check in U\-Boot documentation for these constants and how to use them. .sp There are a further enhancement that can be optionally integrated into U\-boot to make the system safer. The most important I will suggest is to add support for boot counter in U\-boot (documentation is in U\-Boot docs). This allows U\-Boot to track for attempts to successfully run the application, and if the boot counter is greater as a limit, can start automatically SWUpdate to replace a corrupt software. .sp GRUB by default does not support double copies of environment as in case of U\-Boot. This means that there is possibility that environment block get\(aqs corrupted when power\-off occurs during environment update. To minimize the risk, we are not modifying original environment block. Variables are written into temporary file and after successful operation rename instruction is called. .SS Building a single image .sp cpio is used as container for its simplicity. The resulting image is very simple to be built. The file describing the images ("sw\-description", but the name can be configured) must be the first file in the cpio archive. .sp To produce an image, a script like this can be used: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C CONTAINER_VER="1.0" PRODUCT_NAME="my\-software" FILES="sw\-description image1.ubifs \e image2.gz.u\-boot uImage.bin myfile sdcard.img" for i in $FILES;do echo $i;done | cpio \-ov \-H crc > ${PRODUCT_NAME}_${CONTAINER_VER}.swu .ft P .fi .UNINDENT .UNINDENT .sp The single images can be put in any order inside the cpio container, with the exception of sw\-description, that must be the first one. To check your generated image you can run the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C swupdate \-c \-i my\-software_1.0.swu .ft P .fi .UNINDENT .UNINDENT .SS Support of compound image .sp The single image can be built automatically inside Yocto. meta\-swupdate extends the classes with the swupdate class. A recipe should inherit it, and add your own sw\-description file to generate the image. .SH UPDATE STRATEGY EXAMPLES .sp SWUpdate is a building block and it allows one to design and implementing its own update strategy. Even if many projects have common ways for updating, it is possible to high customize the update for each project. The most common strategies (single\-copy and dual\-copy) were already described at the beginning of this documentation and of course are well supported in SWUpdate. .SS Single copy \- running as standalone image .sp See single_copy\&. .SS Double copy with fall\-back .sp See double_copy\&. .SS Combine double\-copy with rescue system .sp This provides a recovery procedure to cover update failure in severe cases when software is damaged. In case none of the copy can be started, the bootloader will start the rescue system (possibly stored on another storage as the main system) to try to rescue the board. [image] .sp The rescue system can be updated as well during a standard update. .SS Split system update with application update .sp Updating a whole image is quite straightforward, but this means to transfer bigger amount of data if just a few files are updated. It is possible to split theupdate in several smaller parts to reduce the transfer size. This requires a special care to take care of compatibility between system and application, that can be solved with customized Lua scripts in the sw\-description file. SWUpdate supports versioning for each artefact, and anyone can add own rules to verify compatibility between components. [image] .SS Configuration update .sp Thought to update the software, SWUpdate can be used to install configuration data as well. Build system can create configuration SWU with files / data for the configuration of the system. There is no requirements what these SWU should contains \- it is duty of the integrator to build them and make them suitable for his own project. Again, configuration data can be updated as separate process using one of the above scenarios. .SH SWUPDATE: SYNTAX AND TAGS WITH THE DEFAULT PARSER .SS Introduction .sp SWUpdate uses the library "libconfig" as default parser for the image description. However, it is possible to extend SWUpdate and add an own parser, based on a different syntax and language as the one supported by libconfig. In the examples directory there is the code for a parser written in Lua, with the description in XML. .sp Using the default parser, sw\-description follows the syntax rules described in the libconfig manual. Please take a look at \fI\%http://www.hyperrealm.com/libconfig/libconfig_manual.html\fP for an explanation of basic types. The whole description must be contained in the sw\-description file itself: using of the #include directive is not allowed by SWUpdate. .sp The following example explains better the implemented tags: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C software = { version = "0.1.0"; description = "Firmware update for XXXXX Project"; hardware\-compatibility: [ "1.0", "1.2", "1.3"]; /* partitions tag is used to resize UBI partitions */ partitions: ( /* UBI Volumes */ { name = "rootfs"; device = "mtd4"; size = 104896512; /* in bytes */ }, { name = "data"; device = "mtd5"; size = 50448384; /* in bytes */ } ); images: ( { filename = "rootfs.ubifs"; volume = "rootfs"; }, { filename = "swupdate.ext3.gz.u\-boot"; volume = "fs_recovery"; }, { filename = "sdcard.ext3.gz"; device = "/dev/mmcblk0p1"; compressed = "zlib"; }, { filename = "bootlogo.bmp"; volume = "splash"; }, { filename = "uImage.bin"; volume = "kernel"; }, { filename = "fpga.txt"; type = "fpga"; }, { filename = "bootloader\-env"; type = "bootloader"; } ); files: ( { filename = "README"; path = "/README"; device = "/dev/mmcblk0p1"; filesystem = "vfat" } ); scripts: ( { filename = "erase_at_end"; type = "lua"; }, { filename = "display_info"; type = "lua"; } ); bootenv: ( { name = "vram"; value = "4M"; }, { name = "addfb"; value = "setenv bootargs ${bootargs} omapfb.vram=1:2M,2:2M,3:2M omapdss.def_disp=lcd" } ); } .ft P .fi .UNINDENT .UNINDENT .sp The first tag is "software". The whole description is contained in this tag. It is possible to group settings per device by using \fI\%Board specific settings\fP\&. .SS Handling configuration differences .sp The concept can be extended to deliver a single image containing the release for multiple devices. Each device has its own kernel, dtb and root filesystem, or they can share some parts. .sp Currently this is managed (and already used in a real project) by writing an own parser, that checks which images must be installed after recognizing which is the device where software is running. .sp Because the external parser can be written in Lua and it is completely customizable, everybody can set his own rules. For this specific example, the sw\-description is written in XML format, with tags identifying the images for each device. To run it, the liblxp library is needed. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Update Image 1.0.0 Firmware for XXXXX Project .ft P .fi .UNINDENT .UNINDENT .sp The parser for this is in the /examples directory. By identifying which is the running device, the parser return a table containing the images that must be installed and their associated handlers. By reading the delivered image, SWUpdate will ignore all images that are not in the list processed by the parser. In this way, it is possible to have a single delivered image for the update of multiple devices. .sp Multiple devices are supported by the default parser, too. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C software = { version = "0.1.0"; target\-1 = { images: ( { ... } ); }; target\-2 = { images: ( { ... } ); }; } .ft P .fi .UNINDENT .UNINDENT .sp In this way, it is possible to have a single image providing software for each device you have. .sp By default the hardware information is extracted from \fI/etc/hwrevision\fP file. The file should contain a single line in the following format: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C .ft P .fi .UNINDENT .UNINDENT .sp Where: .INDENT 0.0 .IP \(bu 2 \fI\fP will be used for matching with hardware compatibility list .IP \(bu 2 \fI\fP can be used for grouping board specific settings .UNINDENT .SS Software collections .sp Software collections and operation modes can be used to implement a dual copy strategy. The simplest case is to define two installation locations for the firmware image and call \fISWUpdate\fP selecting the appropriate image. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C software = { version = "0.1.0"; stable = { copy\-1: { images: ( { device = "/dev/mtd4" ... } ); } copy\-2: { images: ( { device = "/dev/mtd5" ... } ); } }; } .ft P .fi .UNINDENT .UNINDENT .sp In this way it is possible to specify that \fIcopy\-1\fP gets installed to \fI/dev/mtd4\fP, while \fIcopy\-2\fP to \fI/dev/mtd5\fP\&. By properly selecting the installation locations, \fISWUpdate\fP will update the firmware in the other slot. .sp The method of image selection is out of the scope of SWUpdate and user is responsible for calling \fISWUpdate\fP passing proper settings. .SS Priority finding the elements in the file .sp SWUpdate search for entries in the sw\-description file according to the following priority: .INDENT 0.0 .IP 1. 3 Try ... .IP 2. 3 Try .. .IP 3. 3 Try . .IP 4. 3 Try .UNINDENT .sp Take an example. The following sw\-description describes the release for a set of boards. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C software = { version = "0.1.0"; myboard = { stable = { copy\-1: { images: ( { device = "/dev/mtd4" ... } ); } copy\-2: { images: ( { device = "/dev/mtd5" ... } ); } } } stable = { copy\-1: { images: ( { device = "/dev/mtd6" ... } ); } copy\-2: { images: ( { device = "/dev/mtd7" ... } ); } } } .ft P .fi .UNINDENT .UNINDENT .sp On \fImyboard\fP, SWUpdate searches and find myboard.stable.copy1(2). When running on different boards, SWUpdate does not find an entry corresponding to the boardname and it fallbacks to the version without boardname. This lets realize the same release for different boards having a complete different hardware. \fImyboard\fP could have a eMMC and an ext4 filesystem, while another device can have raw flash and install an UBI filesystem. Nevertheless, they are both just a different format of the same release and they could be described together in sw\-description. It is important to understand the priorities how SWUpdate scans for entries during the parsing. .SS Using links .sp sw\-description can become very complex. Let\(aqs think to have just one board, but in multiple hw revision and they differ in Hardware. Some of them can be grouped together, some of them require a dedicated section. A way (but not the only one !) could be to add \fImode\fP and selects the section with \fI\-e stable,\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C software = { version = "0.1.0"; myboard = { stable = { hardware\-compatibility: ["1.0", "1.2", "2.0", "1.§, "3.0", "3.1"]; rev\-1.0: { images: ( ... ); scripts: ( ... ); } rev\-1.2: { hardware\-compatibility: ["1.2"]; images: ( ... ); scripts: ( ... ); } rev\-2.0: { hardware\-compatibility: ["2.0"]; images: ( ... ); scripts: ( ... ); } rev\-1.3: { hardware\-compatibility: ["1.3"]; images: ( ... ); scripts: ( ... ); } rev\-3.0: { hardware\-compatibility: ["3.0"]; images: ( ... ); scripts: ( ... ); } rev\-3.1: { hardware\-compatibility: ["3.1"]; images: ( ... ); scripts: ( ... ); } } } } .ft P .fi .UNINDENT .UNINDENT .sp If each of them requires an own section, it is the way to do. Anyway, it is more probable than revisions can be grouped together, for example board with the same major revision number could have the same installation instructions. This leads in the example to 3 groups for rev1.X, rev2.X and rev3.X. Links allow one to group section together. When a "ref" is found when SWUpdate searches for a group (images, files, script, bootenv), it replaces the current path in the tree with the value of the string. In this way, the example above can be written in this way: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C software = { version = "0.1.0"; myboard = { stable = { hardware\-compatibility: ["1.0", "1.2", "2.0", "1.3, "3.0", "3.1"]; rev\-1x: { images: ( ... ); scripts: ( ... ); } rev1.0 = { ref = "#./rev\-1x"; } rev1.2 = { ref = "#./rev\-1x"; } rev1.3 = { ref = "#./rev\-1x"; } rev\-2x: { images: ( ... ); scripts: ( ... ); } rev2.0 = { ref = "#./rev\-2x"; } rev\-3x: { images: ( ... ); scripts: ( ... ); } rev3.0 = { ref = "#./rev\-3x"; } rev3.1 = { ref = "#./rev\-3x"; } } } } .ft P .fi .UNINDENT .UNINDENT .sp The link can be absolute or relative. The keyword \fI"ref"\fP is used to indicate a link. If this is found, SWUpdate will traverse the tree and replaces the current path with the values find in the string pointed by "ref". There are simple rules for a link: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 it must start with the character \(aq#\(aq .IP \(bu 2 "." points to the current level in the tree, that means the parent of "ref" .IP \(bu 2 ".." points to the parent level in the tree .IP \(bu 2 "/" is used as filed separator in the link .UNINDENT .UNINDENT .UNINDENT .sp A relative path has a number of leading "../" to move the current cursor to the parent leaf of the tree. In the following example, rev40 sets a link to a "common" section, where \fIimages\fP is found. This is sets via a link, too, to a section in the parent node. The path \fIsoftware.myboard.stable.common.images\fP is then replaced by \fIsoftware.myboard.stable.trythis\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C software = { version = { ref = "#./commonversion"; } hardware\-compatibility = ["rev10", "rev11", "rev20"]; commonversion = "0.7\-linked"; pc:{ stable:{ common:{ images = { ref = "#./../trythis"; } }; trythis:( { filename = "rootfs1.ext4"; device = "/dev/mmcblk0p8"; type = "raw"; } , { filename = "rootfs5.ext4"; device = "/dev/mmcblk0p7"; type = "raw"; } ); pdm3rev10: { images:( { filename = "rootfs.ext3"; device = "/dev/mmcblk0p2";} ); uboot:( { name = "bootpart"; value = "0:2";} ); }; pdm3rev11 = { ref = "#./pdm3rev10"; } pdm3rev20 = { ref = "#./pdm3rev10"; } pdm3rev40 = { ref = "#./common"; } }; }; } .ft P .fi .UNINDENT .UNINDENT .sp Each entry in sw\-description can be redirect by a link as in the above example for the "version" attribute. .SS hardware\-compatibility .sp \fBhardware\-compatibility: [ "major.minor", "major.minor", ... ]\fP .sp This entry lists the hardware revisions that are compatible with this software image. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C hardware\-compatibility: [ "1.0", "1.2", "1.3"]; .ft P .fi .UNINDENT .UNINDENT .sp This defines that the software is compatible with HW\-Revisions 1.0, 1.2 and 1.3, but not with 1.1 or any other version not explicitly listed here. In the above example, compatibility is checked by means of string comparison. If the software is compatible with a large number of hardware revisions, it may get cumbersome to enumerate all compatible versions. To allow more compact specifications, regular expressions (POSIX extended) can be used by adding a prefix \fB#RE:\fP to the entry. Rewriting the above example would yield: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C hardware\-compatibility: [ "#RE:^1\e.[023]$" ]; .ft P .fi .UNINDENT .UNINDENT .sp It is in the responsibility of the respective project to find the revision of the board on which SWUpdate is running. No assumptions are made about how the revision can be obtained (GPIOs, EEPROM,..) and each project is free to select the most appropriate way. In the end the result must be written to the file \fB/etc/hwrevision\fP (or in another file if specified as configuration option) before SWUpdate is started. .SS partitions : UBI layout .sp This tag allows one to change the layout of UBI volumes. Please take care that MTDs are not touched and they are configured by the Device Tree or in another way directly in kernel. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C partitions: ( { name = ; size = ; device = ; } ); .ft P .fi .UNINDENT .UNINDENT .sp All fields are mandatory. SWUpdate searches for a volume of the given name and if necessary adjusts size or type (see below). If no volume with the given name is found, a new volume is created on the UBI device attached to the MTD device given by \fBdevice\fP\&. \fBdevice\fP can be specified by number (e.g. "mtd4") or by name (the name of the MTD device, e.g. "ubi_partition"). The UBI device is attached automatically. .sp The default behavior of swupdate is to create a dynamic UBI volume. To create a static volume, add a line \fBdata = "static";\fP to the respective partition entry. .sp If a size of 0 is given, the volume will be deleted if it exists. This can be used to remove orphan volumes possibly created by older software versions which are not required anymore. .SS images .sp The tag "images" collects the image that are installed to the system. The syntax is: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C images: ( { filename[mandatory] = ; volume[optional] = ; device[optional] = ; mtdname[optional] = ; type[optional] = ; /* optionally, the image can be copied at a specific offset */ offset[optional] = ; /* optionally, the image can be compressed if it is in raw mode */ compressed; }, /* Next Image */ ..... ); .ft P .fi .UNINDENT .UNINDENT .sp \fIvolume\fP is only used to install the image in a UBI volume. \fIvolume\fP and \fIdevice\fP cannot be used at the same time. If device is set, the raw handler is automatically selected. .sp The following example is to update a UBI volume: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { filename = "core\-image\-base.ubifs"; volume = "rootfs"; } .ft P .fi .UNINDENT .UNINDENT .sp To update an image in raw mode, the syntax is: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { filename = "core\-image\-base.ext3"; device = "/dev/mmcblk0p1"; } .ft P .fi .UNINDENT .UNINDENT .sp To flash an image at a specific offset, the syntax is: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { filename = "u\-boot.bin"; device = "/dev/mmcblk0p1"; offset = "16K"; } .ft P .fi .UNINDENT .UNINDENT .sp The offset handles the following multiplicative suffixes: K=1024 and M=1024*1024. .sp However, writing to flash in raw mode must be managed in a special way. Flashes must be erased before copying, and writing into NAND must take care of bad blocks and ECC errors. For this reasons, the handler "flash" must be selected: .sp For example, to copy the kernel into the MTD7 of a NAND flash: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { filename = "uImage"; device = "mtd7"; type = "flash"; } .ft P .fi .UNINDENT .UNINDENT .sp The \fIfilename\fP is mandatory. It is the Name of the file extracted by the stream. \fIvolume\fP is only mandatory in case of UBI volumes. It should be not used in other cases. .sp Alternatively, for the handler “flash”, the \fImtdname\fP can be specified, instead of the device name: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { filename = "uImage"; mtdname = "kernel"; type = "flash"; } .ft P .fi .UNINDENT .UNINDENT .SS Files .sp It is possible to copy single files instead of images. This is not the preferred way, but it can be used for debugging or special purposes. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C files: ( { filename = ; path = ; device[optional] = ; filesystem[optional] = ; properties[optional] = {create\-destination = "true";} } ); .ft P .fi .UNINDENT .UNINDENT .sp Entries in "files" section are managed as single files. The attributes "filename" and "path" are mandatory. Attributes "device" and "filesystem" are optional; they tell SWUpdate to mount device (of the given filesystem type, e.g. "ext4") before copying "filename" to "path". Without "device" and "filesystem", the "filename" will be copied to "path" in the current rootfs. .sp As a general rule, swupdate doesn\(aqt copy out a file if the destination path doesn\(aqt exists. This behavior could be changed using the special property "create\-destination". .SS Scripts .sp Scripts runs in the order they are put into the sw\-description file. The result of a script is valuated by SWUpdate, that stops the update with an error if the result is <> 0. .sp They are copied into a temporary directory before execution and their name must be unique inside the same cpio archive. .sp If no type is given, SWUpdate default to "lua". .SS Lua .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C scripts: ( { filename = ; type = "lua"; } ); .ft P .fi .UNINDENT .UNINDENT .sp Lua scripts are run using the internal interpreter. .sp They must have at least one of the following functions: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C function preinst() .ft P .fi .UNINDENT .UNINDENT .sp SWUpdate scans for all scripts and check for a preinst function. It is called before installing the images. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C function postinst() .ft P .fi .UNINDENT .UNINDENT .sp SWUpdate scans for all scripts and check for a postinst function. It is called after installing the images. .SS shellscript .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C scripts: ( { filename = ; type = "shellscript"; } ); .ft P .fi .UNINDENT .UNINDENT .sp Shell scripts are called via system command. SWUpdate scans for all scripts and calls them before and after installing the images. SWUpdate passes \(aqpreinst\(aq or \(aqpostinst\(aq as first argument to the script. If the data attribute is defined, its value is passed as the last argument(s) to the script. .SS preinstall .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C scripts: ( { filename = ; type = "preinstall"; } ); .ft P .fi .UNINDENT .UNINDENT .sp preinstall are shell scripts and called via system command. SWUpdate scans for all scripts and calls them before installing the images. If the data attribute is defined, its value is passed as the last argument(s) to the script. .SS postinstall .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C scripts: ( { filename = ; type = "postinstall"; } ); .ft P .fi .UNINDENT .UNINDENT .sp postinstall are shell scripts and called via system command. SWUpdate scans for all scripts and calls them after installing the images. If the data attribute is defined, its value is passed as the last argument(s) to the script. .SS Update Transaction Marker .sp By default, SWUpdate sets the bootloader environment variable "recovery_status" to "in_progress" prior to an update operation and either unsets it or sets it to "failed" after the update operation. This is an interface for SWUpdate\-external tooling: If there is no "recovery_status" variable in the bootloader\(aqs environment, the update operation has been successful. Else, if there is a "recovery_status" variable with the value "failed", the update operation has not been successful. .sp While this is in general essential behavior for firmware updates, it needn\(aqt be for less critical update operations. Hence, whether or not the update transaction marker is set by SWUpdate can be controlled by the boolean switch "bootloader_transaction_marker" which is global per \fIsw\-description\fP file. It defaults to \fBtrue\fP\&. The following example snippet disables the update transaction marker: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C software = { version = "0.1.0"; bootloader_transaction_marker = false; ... .ft P .fi .UNINDENT .UNINDENT .sp It is also possible to disable setting of the transaction marker entirely (and independently of the setting in \fIsw\-description\fP) by starting swupdate with the \fI\-M\fP option. .SS bootloader .sp There are two ways to update the bootloader (currently U\-Boot, GRUB, and EFI Boot Guard) environment. First way is to add a file with the list of variables to be changed and setting "bootloader" as type of the image. This informs SWUpdate to call the bootloader handler to manage the file (requires enabling bootloader handler in configuration). There is one bootloader handler for all supported bootloaders. The appropriate bootloader must be chosen from the bootloader selection menu in \fImenuconfig\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C images: ( { filename = "bootloader\-env"; type = "bootloader"; } ) .ft P .fi .UNINDENT .UNINDENT .sp The format of the file is described in U\-boot documentation. Each line is in the format .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C = .ft P .fi .UNINDENT .UNINDENT .sp if value is missing, the variable is unset. .sp The format is compatible with U\-Boot "env import" command. It is possible to produce the file from target as result of "env export". .sp Comments are allowed in the file to improve readability, see this example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Default variables bootslot=0 board_name=myboard baudrate=115200 ## Board Revision dependent board_revision=1.0 .ft P .fi .UNINDENT .UNINDENT .sp The second way is to define in a group setting the variables that must be changed: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C bootenv: ( { name = ; value = ; } ) .ft P .fi .UNINDENT .UNINDENT .sp SWUpdate will internally generate a script that will be passed to the bootloader handler for adjusting the environment. .sp For backward compatibility with previously built \fI\&.swu\fP images, the "uboot" group name is still supported as an alias. However, its usage is deprecated. .SS Board specific settings .sp Each setting can be placed under a custom tag matching the board name. This mechanism can be used to override particular setting in board specific fashion. .sp Assuming that the hardware information file \fI/etc/hwrevision\fP contains the following entry: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-board 0.1.0 .ft P .fi .UNINDENT .UNINDENT .sp and the following description: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C software = { version = "0.1.0"; my\-board = { bootenv: ( { name = "bootpart"; value = "0:2"; } ); }; bootenv: ( { name = "bootpart"; value = "0:1"; } ); } .ft P .fi .UNINDENT .UNINDENT .sp SWUpdate will set \fIbootpart\fP to \fI0:2\fP in bootloader\(aqs environment for this board. For all other boards, \fIbootpart\fP will be set to \fI0:1\fP\&. Board specific settings take precedence over default scoped settings. .SS Software collections and operation modes .sp Software collections and operations modes extend the description file syntax to provide an overlay grouping all previous configuration tags. The mechanism is similar to \fI\%Board specific settings\fP and can be used for implementing a dual copy strategy or delivering both stable and unstable images within a single update file. .sp The mechanism uses a custom user\-defined tags placed within \fIsoftware\fP scope. The tag names must not be any of: \fIversion\fP, \fIhardware\-compatibility\fP, \fIuboot\fP, \fIbootenv\fP, \fIfiles\fP, \fIscripts\fP, \fIpartitions\fP, \fIimages\fP .sp An example description file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C software = { version = "0.1"; hardware\-compatibility = [ "revA" ]; /* differentiate running image modes/sets */ stable: { main: { images: ( { filename = "rootfs.ext3"; device = "/dev/mmcblk0p2"; } ); bootenv: ( { name = "bootpart"; value = "0:2"; } ); }; alt: { images: ( { filename = "rootfs.ext3"; device = "/dev/mmcblk0p1"; } ); bootenv: ( { name = "bootpart"; value = "0:1"; } ); }; }; } .ft P .fi .UNINDENT .UNINDENT .sp The configuration describes a single software collection named \fIstable\fP\&. Two distinct image locations are specified for this collection: \fI/dev/mmcblk0p1\fP and \fI/dev/mmcblk0p2\fP for \fImain\fP mode and \fIalt\fP mode respectively. .sp This feature can be used to implement a dual copy strategy by specifying the collection and mode explicitly. .SS Checking version of installed software .sp SWUpdate can optionally verify if a sub\-image is already installed and, if the version to be installed is exactly the same, it can skip to install it. This is very useful in case some high risky image should be installed or to speed up the upgrade process. One case is if the bootloader needs to be updated. In most time, there is no need to upgrade the bootloader, but practice showed that there are some cases where an upgrade is strictly required \- the project manager should take the risk. However, it is nicer to have always the bootloader image as part of the .swu file, allowing to get the whole distro for the device in a single file, but the device should install it just when needed. .sp SWUpdate searches for a file (/etc/sw\-versions is the default location) containing all versions of the installed images. This must be generated before running SWUpdate. The file must contains pairs with the name of image and his version, as: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C .ft P .fi .UNINDENT .UNINDENT .sp In sw\-description, the optional attributes "name", "version" and "install\-if\-different" provide the connection. Name and version are then compared with the data in the versions file. install\-if\-different is a boolean that enables the check for this image. It is then possible to check the version just for a subset of the images to be installed. .sp If used with "install\-if\-different", then version can be any string. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C bootloader 2015.01\-rc3\-00456\-gd4978d kernel 3.17.0\-00215\-g2e876af .ft P .fi .UNINDENT .UNINDENT .sp There is also an attribute "install\-if\-higher" that checks if the version of the new software is higher than the version of the installed software. If it\(aqs false, the new software isn\(aqt installed. The goal is to avoid installing an older version of software. .sp In this case, version can be any of 2 formats. Either the version consists of \fIup to\fP 4 numbers separated by a dot, e.g. \fI...\fP, or it is a \fI\%semantic version\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C bootloader 2018.03.01 kernel 3.17.0\-pre1+g2e876af rfs 0.17\-foo3.bar5+2020.07.01 app 1.7 .ft P .fi .UNINDENT .UNINDENT .sp It is advised not to mix version formats! Semantic versions only support 3 numbers (major, minor, patch) and the fourth number will be silently dropped if present. .SS Embedded Script .sp It is possible to embed a script inside sw\-description. This is useful in a lot of conditions where some parameters are known just by the target at runtime. The script is global to all sections, but it can contain several functions that can be specific for each entry in the sw\-description file. .sp These attributes are used for an embedded\-script: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C embedded\-script = " .ft P .fi .UNINDENT .UNINDENT .sp It must be taken into account that the parser has already run and usage of double quotes can interfere with the parser. For this reason, each double quote in the script must be escaped. .sp That means a simple Lua code as: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C print ("Test") .ft P .fi .UNINDENT .UNINDENT .sp must be changed to: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C print (\e"Test\e") .ft P .fi .UNINDENT .UNINDENT .sp If not, the parser thinks to have the closure of the script and this generates an error. See the examples directory for examples how to use it. Any entry in files or images can trigger one function in the script. The "hook" attribute tells the parser to load the script and to search for the function pointed to by the hook attribute. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C files: ( { filename = "examples.tar"; type = "archive"; path = "/tmp/test"; hook = "set_version"; preserve\-attributes = true; } ); .ft P .fi .UNINDENT .UNINDENT .sp After the entry is parsed, the parser runs the Lua function pointed to by hook. If Lua is not activated, the parser raises an error because a sw\-description with an embedded script must be parsed, but the interpreter is not available. .sp Each Lua function receives as parameter a table with the setup for the current entry. A hook in Lua is in the format: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C function lua_hook(image) .ft P .fi .UNINDENT .UNINDENT .sp image is a table where the keys are the list of available attributes. If an attribute contains a "\-", it is replaced with "_", because "\-" cannot be used in Lua. This means, for example, that: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C install\-if\-different ==> install_if_different install\-directly ==> install_directly .ft P .fi .UNINDENT .UNINDENT .sp Attributes can be changed in the Lua script and values are taken over on return. The Lua function must return 2 values: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 a boolean, to indicate whether the parsing was correct .IP \(bu 2 the image table or nil to indicate that the image should be skipped .UNINDENT .UNINDENT .UNINDENT .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C function set_version(image) print (\e"RECOVERY_STATUS.RUN: \e".. swupdate.RECOVERY_STATUS.RUN) for k,l in pairs(image) do swupdate.trace(\e"image[\e" .. tostring(k) .. \e"] = \e" .. tostring(l)) end image.version = \e"1.0\e" image.install_if_different = true return true, image end .ft P .fi .UNINDENT .UNINDENT .sp The example sets a version for the installed image. Generally, this is detected at runtime reading from the target. .SS Attribute reference .sp There are 4 main sections inside sw\-description: .INDENT 0.0 .IP \(bu 2 images: entries are images and SWUpdate has no knowledge about them. .IP \(bu 2 files: entries are files, and SWUpdate needs a filesystem for them. This is generally used to expand from a tar\-ball or to update single files. .IP \(bu 2 scripts: all entries are treated as executables, and they will be run twice (as pre\- and post\- install scripts). .IP \(bu 2 bootenv: entries are pair with bootloader environment variable name and its value. .UNINDENT .SS Attributes in sw\-description .TS center; |l|l|l|l|. _ T{ Name T} T{ Type T} T{ Applies to T} T{ Description T} _ T{ filename T} T{ string T} T{ images files scripts T} T{ filename as found in the cpio archive T} _ T{ volume T} T{ string T} T{ images T} T{ Just if type = "ubivol". UBI volume where image must be installed. T} _ T{ ubipartition T} T{ string T} T{ images T} T{ Just if type = "ubivol". Volume to be created or adjusted with a new size T} _ T{ device T} T{ string T} T{ images files T} T{ devicenode as found in /dev or a symlink to it. Can be specified as absolute path or a name in /dev folder For example if /dev/mtd\-dtb is a link to /dev/mtd3 "mtd3", "mtd\-dtb", "/dev/mtd3" and "/dev/mtd\-dtb" are valid names. Usage depends on handler. For files, it indicates on which device the "filesystem" must be mounted. If not specified, the current rootfs will be used. T} _ T{ filesystem T} T{ string T} T{ files T} T{ indicates the filesystem type where the file must be installed. Only used if "device" attribute is set. T} _ T{ path T} T{ string T} T{ files T} T{ For files: indicates the path (absolute) where the file must be installed. If "device" and "filesystem" are set, SWUpdate will install the file after mounting "device" with "filesystem" type. (path is always relative to the mount point.) T} _ T{ preserve\-attributes T} T{ bool T} T{ files T} T{ flag to control whether the following attributes will be preserved when files are unpacked from an archive (assuming destination filesystem supports them, of course): timestamp, uid/gid (numeric), perms, file attributes, extended attributes T} _ T{ type T} T{ string T} T{ images files scripts T} T{ string identifier for the handler, as it is set by the handler when it regitsters itself. Example: "ubivol", "raw", "rawfile", T} _ T{ compressed T} T{ string T} T{ images files T} T{ string to indicate the "filename" is compressed and must be decompressed before being installed. the value denotes the compression type. currently supported values are "zlib" and "zstd". T} _ T{ compressed T} T{ bool (dep recated) T} T{ images files T} T{ Deprecated. Use the string form. true is equal to \(aqcompression = "zlib"\(aq. T} _ T{ installed\-directly T} T{ bool T} T{ images T} T{ flag to indicate that image is streamed into the target without any temporary copy. Not all handlers support streaming. T} _ T{ name T} T{ string T} T{ bootenv T} T{ name of the bootloader variable to be set. T} _ T{ value T} T{ string T} T{ bootenv T} T{ value to be assigned to the bootloader variable T} _ T{ name T} T{ string T} T{ images files T} T{ name that identifies the sw\-component it can be any string and it is compared with the entries in sw\-versions T} _ T{ version T} T{ string T} T{ images files T} T{ version for the sw\-component it can be any string and it is compared with the entries in sw\-versions T} _ T{ description T} T{ string T} T{ T} T{ user\-friendly description of the swupdate archive (any string) T} _ T{ install\-if\-different T} T{ bool T} T{ images files T} T{ flag if set, name and version are compared with the entries in T} _ T{ install\-if\-higher T} T{ bool T} T{ images files T} T{ flag if set, name and version are compared with the entries in T} _ T{ encrypted T} T{ bool T} T{ images files scripts T} T{ flag if set, file is encrypted and must be decrypted before installing. T} _ T{ ivt T} T{ string T} T{ images files scripts T} T{ IVT in case of encrypted artefact It has no value if "encrypted" is not set. Each artefact can have an own IVT to avoid attacker can guess the the key. It is a ASCII string of 32 chars T} _ T{ data T} T{ string T} T{ images files scripts T} T{ This is used to pass arbitrary data to a handler. T} _ T{ sha256 T} T{ string T} T{ images files scripts T} T{ sha256 hash of image, file or script. Used for verification of signed images. T} _ T{ embedded\-script T} T{ string T} T{ T} T{ Lua code that is embedded in the sw\-description file. T} _ T{ offset T} T{ string T} T{ images T} T{ Optional destination offset T} _ T{ hook T} T{ string T} T{ images files T} T{ The name of the function (Lua) to be called when the entry is parsed. T} _ T{ mtdname T} T{ string T} T{ images T} T{ name of the MTD to update. Used only by the flash handler to identify the the mtd to update, instead of specifying the devicenode T} _ .TE .SH UPDATE IMAGES FROM VERIFIED SOURCE .sp It is becoming very important that a device must not only be safely updated, but also that it can verify if the delivered image is coming from a known source and it was not corrupted introducing some malware. .sp To achieve this goal, SWUpdate must verify the incoming images. There are several ways to do this. Should the compound image be signed ? Or some parts of it ? .sp Advantages and disadvantages are described in the following chapter. .SS Signing the compound image .sp It looks quite straightforward if the whole compound image is signed. However, this has some heavy drawbacks. It is not possible to know if the image is verified until the whole image is loaded. This means that verification can be done after installing the single images instead of doing it before touching the device. This leads to have some uninstall procedure if part of a not verified image is already installed, procedures that cannot be safe in case of power off letting some unwanted piece of software on the device. .SS Signing the sub\-images .sp If each sub\-image is signed, the verification is done before calling the corresponding hardware. Only signed images can be installed. Anyway, this remains unbound with the description of the release in sw\-description. Even if sw\-description is signed, an attacker can mix signed images together generating a new compound image that can be installed as well, because all sub\-images are verified. .SS Combining signing sw\-description with hash verification .sp To avoid the described drawbacks, SWUpdate combines signed sw\-description with the verification of hashes for each single image. This means that only sw\-description generated by a verified source can be accepted by the installer. sw\-description contains hashes for each sub\-image to verify that each delivered sub\-image really belongs to the release. .SS Choice of algorithm .sp The algorithm chosen to sign and verify the sw\-descrription file can be selected via menuconfig. Currently, the following mechanisms are implemented: .INDENT 0.0 .IP \(bu 2 RSA Public / private key. The private key belongs to the build system, while the public key must be installed on the target. .IP \(bu 2 CMS using certificates .UNINDENT .sp Key or certificate is passed to SWUpdate with the \fI\-k\fP parameter. .SS Tool to generate keys / certificates .sp The \fIopenssl\fP tool is used to generate the keys. This is part of the OpenSSL project. A complete documentation can be found at the \fI\%openSSL Website\fP\&. .SS Usage with RSA PKCS#1.5 or RSA PSS .SS Generating private and public key .sp First, the private key must be created: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C openssl genrsa \-aes256 \-out priv.pem .ft P .fi .UNINDENT .UNINDENT .sp This asks for a passphrase. It is possible to retrieve the passphrase from a file \- of course, this must be protected against intrusion. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C openssl genrsa \-aes256 \-passout file:passout \-out priv.pem .ft P .fi .UNINDENT .UNINDENT .sp The private key is used to export the public key with: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C openssl rsa \-in priv.pem \-out public.pem \-outform PEM \-pubout .ft P .fi .UNINDENT .UNINDENT .sp "public.pem" contains the key in a format suitable for swupdate. The file can be passed to swupdate at the command line with the \-k parameter. .SS How to sign with RSA .sp Signing the image with rsa\-pkcs#1.5 is very simple: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C openssl dgst \-sha256 \-sign priv.pem sw\-description > sw\-description.sig .ft P .fi .UNINDENT .UNINDENT .sp Signing the image with rsa\-pss is also very simple: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C openssl dgst \-sha256 \-sign priv.pem \-sigopt rsa_padding_mode:pss \e \-sigopt rsa_pss_saltlen:\-2 sw\-description > sw\-description.sig .ft P .fi .UNINDENT .UNINDENT .SS Usage with certificates and CMS .SS Generating self\-signed certificates .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C openssl req \-x509 \-newkey rsa:4096 \-nodes \-keyout mycert.key.pem \e \-out mycert.cert.pem \-subj "/O=SWUpdate /CN=target" .ft P .fi .UNINDENT .UNINDENT .sp Check the documentation for more information about parameters. The "mycert.key.pem" contains the private key and it is used for signing. It is \fInot\fP delivered on the target. .sp The target must have "mycert.cert.pem" installed \- this is used by SWUpdate for verification. .SS Using PKI issued certificates .sp It is also possible to use PKI issued code signing certificates. However, SWUpdate uses OpenSSL library for handling CMS signatures and the library requires the following attributes to be set on the signing certificate: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C keyUsage=digitalSignature extendedKeyUsage=emailProtection .ft P .fi .UNINDENT .UNINDENT .sp It is also possible to completely disable signing certificate key usage checking if this requirement cannot be satisfied. This is controlled by \fICONFIG_CMS_IGNORE_CERTIFICATE_PURPOSE\fP configuration option. .SS How to sign with CMS .sp Signing the image is simple as in the previous case: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C openssl cms \-sign \-in sw\-description \-out sw\-description.sig \-signer mycert.cert.pem \e \-inkey mycert.key.pem \-outform DER \-nosmimecap \-binary .ft P .fi .UNINDENT .UNINDENT .SS Building a signed SWU image .sp There are two files, sw\-description and its signature sw\-description.sig. The signature file must always directly follow the description file. .sp Each image inside sw\-description must have the attribute "sha256", with the SHA256 sum of the image. If an image does not have the sha256 attribute, the whole compound image results as not verified and SWUpdate stops with an error before starting to install. .sp A simple script to create a signed image can be: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #!/bin/bash MODE="RSA\-PKCS\-1.5" PRODUCT_NAME="myproduct" CONTAINER_VER="1.0" IMAGES="rootfs kernel" FILES="sw\-description sw\-description.sig $IMAGES" #if you use RSA if [ x"$MODE" == "xRSA\-PKCS\-1.5" ]; then openssl dgst \-sha256 \-sign priv.pem sw\-description > sw\-description.sig elif if [ x"$MODE" == "xRSA\-PSS" ]; then openssl dgst \-sha256 \-sign priv.pem \-sigopt rsa_padding_mode:pss \e \-sigopt rsa_pss_saltlen:\-2 sw\-description > sw\-description.sig else openssl cms \-sign \-in sw\-description \-out sw\-description.sig \-signer mycert.cert.pem \e \-inkey mycert.key.pem \-outform DER \-nosmimecap \-binary fi for i in $FILES;do echo $i;done | cpio \-ov \-H crc > ${PRODUCT_NAME}_${CONTAINER_VER}.swu .ft P .fi .UNINDENT .UNINDENT .SS Example for sw\-description with signed image .sp The example applies to a Beaglebone, installing Yocto images: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C software = { version = "0.1.0"; hardware\-compatibility: [ "revC"]; images: ( { filename = "core\-image\-full\-cmdline\-beaglebone.ext3"; device = "/dev/mmcblk0p2"; type = "raw"; sha256 = "43cdedde429d1ee379a7d91e3e7c4b0b9ff952543a91a55bb2221e5c72cb342b"; } ); scripts: ( { filename = "test.lua"; type = "lua"; sha256 = "f53e0b271af4c2896f56a6adffa79a1ffa3e373c9ac96e00c4cfc577b9bea5f1"; } ); } .ft P .fi .UNINDENT .UNINDENT .SS Running SWUpdate with signed images .sp Verification is activated by setting CONFIG_SIGNED_IMAGES in SWUpdate\(aqs configuration. If activated, SWUpdate will always check the compound image. For security reasons, it is not possible to disable the check at runtime. The \-k parameter (public key file) is mandatory and the program stops if the public key is not passed. .SH SYMMETRICALLY ENCRYPTED UPDATE IMAGES .sp SWUpdate allows one to symmetrically encrypt update images using the AES block cipher in CBC mode. The following shows encryption with 256 bit key length but you may use other key lengths as well. .SS Building an Encrypted SWU Image .sp First, create a key via \fIopenssl\fP which is part of the OpenSSL project. A complete documentation can be found at the \fI\%OpenSSL Website\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C openssl enc \-aes\-256\-cbc \-k \-P \-md sha1 .ft P .fi .UNINDENT .UNINDENT .sp The key and initialization vector is generated based on the given \fB\fP\&. The output of the above command looks like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt=CE7B0488EFBF0D1B key=B78CC67DD3DC13042A1B575184D4E16D6A09412C242CE253ACEE0F06B5AD68FC iv =65D793B87B6724BB27954C7664F15FF3 .ft P .fi .UNINDENT .UNINDENT .sp Then, encrypt an image using this information via .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C openssl enc \-aes\-256\-cbc \-in \-out \-K \-iv .ft P .fi .UNINDENT .UNINDENT .sp where \fB\fP is the unencrypted source image file and \fB\fP is the encrypted output image file to be referenced in \fBsw\-description\fP\&. \fB\fP is the hex value part of the 2nd line of output from the key generation command above and \fB\fP is the hex value part of the 3rd line. .sp Then, create a key file to be supplied to SWUpdate via the \fI\-K\fP switch by putting the key and initialization vector hex values on one line separated by whitespace, e.g., for above example values .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C B78CC67DD3DC13042A1B575184D4E16D6A09412C242CE253ACEE0F06B5AD68FC 65D793B87B6724BB27954C7664F15FF3 .ft P .fi .UNINDENT .UNINDENT .sp For earlier versions of SWUpdate it was falsely noted that passing the SALT as a 3rd parameter would increase security. Key and IV are enough for maximum security, salt doesn\(aqt add any value. .sp You should change the IV with every encryption, see \fI\%CWE\-329\fP\&. The \fBivt\fP sw\-description attribute overrides the key file\(aqs IV for one specific image. .SS Encryption of UBI volumes .sp Due to a limit in the Linux kernel API for UBI volumes, the size reserved to be written on disk should be declared before actually writing anything. .sp See the property "decrypted\-size" in UBI Volume Handler\(aqs documentation. .SS Example sw\-description with Encrypted Image .sp The following example is a (minimal) \fBsw\-description\fP for installing a Yocto image onto a Beaglebone. Pay attention to the \fBencrypted = true;\fP setting. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C software = { version = "0.0.1"; images: ( { filename = "core\-image\-full\-cmdline\-beaglebone.ext3.enc"; device = "/dev/mmcblk0p3"; encrypted = true; ivt = "65D793B87B6724BB27954C7664F15FF3"; } ); } .ft P .fi .UNINDENT .UNINDENT .SS Running SWUpdate with Encrypted Images .sp Symmetric encryption support is activated by setting the \fBENCRYPTED_IMAGES\fP option in SWUpdate\(aqs configuration. Use the \fI\-K\fP parameter to provide the symmetric key file generated above to SWUpdate. .SS Decrypting with a PKCS#11 token .sp PKCS#11 support is activated by setting the \fBPKCS11\fP option in SWUpdate\(aqs configuration. The key file has to have a PKCS#11 URL instead of the key then, containing at least the elements of this example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pkcs11:slot\-id=42;id=%CA%FE%BA%BE?pin\-value=1234&module\-path=/usr/lib/libsofthsm2.so 65D793B87B6724BB27954C7664F15FF3 .ft P .fi .UNINDENT .UNINDENT .SH HANDLERS .SS Overview .sp It is quite difficult to foresee all possible installation cases. Instead of trying to find all use cases, SWUpdate let the developer free to add his own installer (that is, a new \fBhandler\fP), that must be responsible to install an image of a certain type. An image is marked to be of a defined type to be installed with a specific handler. .sp The parser make the connection between \(aqimage type\(aq and \(aqhandler\(aq. It fills a table containing the list of images to be installed with the required handler to execute the installation. Each image can have a different installer. .SS Supplied handlers .INDENT 0.0 .TP .B In mainline there are the handlers for the most common cases. They include: .INDENT 7.0 .IP \(bu 2 flash devices in raw mode (both NOR and NAND) .IP \(bu 2 UBI volumes .IP \(bu 2 UBI volumes partitioner .IP \(bu 2 raw flashes handler (NAND, NOR, SPI\-NOR, CFI interface) .IP \(bu 2 disk partitioner .IP \(bu 2 raw devices, such as a SD Card partition .IP \(bu 2 bootloader (U\-Boot, GRUB, EFI Boot Guard) environment .IP \(bu 2 Lua scripts handler .IP \(bu 2 shell scripts handler .IP \(bu 2 rdiff handler .IP \(bu 2 readback handler .IP \(bu 2 archive (zo, tarballs) handler .IP \(bu 2 remote handler .IP \(bu 2 microcontroller update handler .UNINDENT .UNINDENT .sp For example, if an image is marked to be updated into a UBI volume, the parser must fill a supplied table setting "ubi" as required handler, and filling the other fields required for this handler: name of volume, size, and so on. .SS Creating own handlers .sp SWUpdate can be extended with new handlers. The user needs to register his own handler with the core and he must provide the callback that SWUpdate uses when an image required to be installed with the new handler. .sp The prototype for the callback is: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C int my_handler(struct img_type *img, void __attribute__ ((__unused__)) *data) .ft P .fi .UNINDENT .UNINDENT .sp The most important parameter is the pointer to a struct img_type. It describes a single image and inform the handler where the image must be installed. The file descriptor of the incoming stream set to the start of the image to be installed is also part of the structure. .sp The structure \fIimg_type\fP contains the file descriptor of the stream pointing to the first byte of the image to be installed. The handler must read the whole image, and when it returns back SWUpdate can go on with the next image in the stream. .sp SWUpdate provides a general function to extract data from the stream and copy to somewhere else: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C int copyfile(int fdin, int fdout, int nbytes, unsigned long *offs, int skip_file, int compressed, uint32_t *checksum, unsigned char *hash); .ft P .fi .UNINDENT .UNINDENT .sp fdin is the input stream, that is img\->fdin from the callback. The \fIhash\fP, in case of signed images, is simply passed to copyfile() to perform the check, exactly as the \fIchecksum\fP parameter. copyfile() will return an error if checksum or hash do not match. The handler does not need to bother with them. How the handler manages the copied data, is specific to the handler itself. See supplied handlers code for a better understanding. .sp The handler\(aqs developer registers his own handler with a call to: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C __attribute__((constructor)) void my_handler_init(void) { register_handler("mytype", my_handler, my_mask, data); } .ft P .fi .UNINDENT .UNINDENT .sp SWUpdate uses the gcc constructors, and all supplied handlers are registered when SWUpdate is initialized. .sp register_handler has the syntax: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C register_handler(my_image_type, my_handler, my_mask, data); .ft P .fi .UNINDENT .UNINDENT .sp Where: .INDENT 0.0 .IP \(bu 2 my_image_type : string identifying the own new image type. .IP \(bu 2 my_handler : pointer to the installer to be registered. .IP \(bu 2 my_mask : \fBHANDLER_MASK\fP enum value(s) specifying what input type(s) my_handler can process. .IP \(bu 2 data : an optional pointer to an own structure, that SWUpdate saves in the handlers\(aq list and pass to the handler when it will be executed. .UNINDENT .SS UBI Volume Handler .sp The UBI volume handler will update UBI volumes without changing the layout on the storage. Therefore, volumes must be created/adjusted beforehand. This can be done using the \fBpartitions\fP tag (see partitions\-ubi\-layout). .sp The UBI volume handler will search for volumes in all MTD devices (unless blacklisted, see UBIBLACKLIST) to find the volume into which the image shall be installed. For this reason, \fBvolume names must be unique\fP within the system. Two volumes with the same name are not supported and will lead to unpredictable results (SWUpdate will install the image to the first volume with that name it finds, which may not be right one!). .sp When updating volumes, it is guaranteed that erase counters are preserved and not lost. The behavior of updating is identical to that of the \fBubiupdatevol(1)\fP tool from mtd\-utils. In fact, the same library from mtd\-utils (libubi) is reused by SWUpdate. .SS atomic volume renaming .sp The UBI volume handler has basic support for carrying out atomic volume renames by defining the \fBreplaces\fP property, which must contain a valid UBI volume name. After successfully updating the image to \fBvolume\fP, an atomic swap of the names of \fBvolume\fP and \fBreplaces\fP is done. Consider the following example .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { filename ="u\-boot.img"; volume ="u\-boot_r"; properties: { replaces = "u\-boot"; } } .ft P .fi .UNINDENT .UNINDENT .sp After u\-boot.img is successfully installed into the volume "u\-boot_r", the volume "u\-boot_r" is renamed to "u\-boot" and "u\-boot" is renamed to "u\-boot_r". .sp This mechanism allows one to implement a simple double copy update approach without the need of shared state with the bootloader. For example, the U\-Boot SPL can be configured to always load U\-Boot from the volume \fBu\-boot\fP without the need to access the environment. The volume replace functionality will ensure that this volume name always points to the currently valid volume. .sp However, please note the following limitations: .INDENT 0.0 .IP \(bu 2 Currently the rename takes place after \fIeach\fP image was installed successfully. Hence, it only makes sense to use this feature for images that are independent of the other installed images. A typical example is the bootloader. This behavior may be modified in the future to only carry out one atomic rename after all images were installed successfully. .IP \(bu 2 Atomic renames are only possible and permitted for volumes residing on the same UBI device. .UNINDENT .sp There is a handler ubiswap that allow one to do an atomic swap for several ubi volume after all the images were flashed. This handler is a script for the point of view of swudate, so the node that provide it the data should be added in the section scripts. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C scripts: ( { type = "ubiswap"; properties: { swap\-0 = [ "boot" , " boot_r" ]; swap\-1 = [ "kernel" , "kernel_r" ]; swap\-2 = [ "rootfs" , "rootfs_r" ]; }, }, ); .ft P .fi .UNINDENT .UNINDENT .sp WARNING: if you use the property replaces on an ubi volume that is also used with the handler ubiswap, this ubi volume will be swapped twice. It\(aqs probably not what you want ... .SS volume auto resize .sp The UBI volume handler has support to auto resize before flashing an image with the property \fBauto\-resize\fP\&. When this property is set on an image, the ubi volume is resized to fit exactly the image. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { filename = "u\-boot.img"; device = "mtd0"; volume = "u\-boot_r"; properties: { auto\-resize = "true"; } } .ft P .fi .UNINDENT .UNINDENT .sp WARNING: when this property is used, the device must be defined. .SS volume always remove .sp The UBI volume handler has support to always remove ubi volume before flashing with the property \fBalways\-remove\fP\&. When this property is set on an image, the ubi volume is always removed. This property should be used with property \fBauto\-resize\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { filename = "u\-boot.img"; device = "mtd0"; volume = "u\-boot_r"; properties: { always\-remove = "true"; auto\-resize = "true"; } } .ft P .fi .UNINDENT .UNINDENT .SS size properties .sp Due to a limit in the Linux kernel API for UBI volumes, the size reserved to be written on disk should be declared before actually writing anything. Unfortunately, the size of an encrypted or compressed image is not known until the decryption or decompression finished. This prevents correct declaration of the file size to be written on disk. .sp For this reason UBI images can declare the special properties "decrypted\-size" or "decompressed\-size" like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C images: ( { filename = "rootfs.ubifs.enc"; volume = "rootfs"; encrypted = true; properties: { decrypted\-size = "104857600"; } }, { filename = "homefs.ubifs.gz"; volume = "homefs"; compressed = "zlib"; properties: { decompressed\-size = "420000000"; } } ); .ft P .fi .UNINDENT .UNINDENT .sp The real size of the image should be calculated and written to the sw\-description before assembling the cpio archive. In this example, 104857600 is the size of the rootfs after the decryption: the encrypted size is by the way larger. The decompressed size is of the homefs is 420000000. .sp The sizes are bytes in decimal notation. .SS Lua Handlers .sp In addition to the handlers written in C, it is possible to extend SWUpdate with handlers written in Lua that get loaded at SWUpdate startup. The Lua handler source code file may either be embedded into the SWUpdate binary via the \fBCONFIG_EMBEDDED_LUA_HANDLER\fP config option or has to be installed on the target system in Lua\(aqs search path as \fBswupdate_handlers.lua\fP so that it can be loaded by the embedded Lua interpreter at run\-time. .sp In analogy to C handlers, the prototype for a Lua handler is .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C function lua_handler(image) ... end .ft P .fi .UNINDENT .UNINDENT .sp where \fBimage\fP is a Lua table (with attributes according to sw\-description\(aqs attribute reference) that describes a single artifact to be processed by the handler. .sp Note that dashes in the attributes\(aq names are replaced with underscores for the Lua domain to make them idiomatic, e.g., \fBinstalled\-directly\fP becomes \fBinstalled_directly\fP in the Lua domain. .sp To register a Lua handler, the \fBswupdate\fP module provides the \fBswupdate.register_handler()\fP method that takes the handler\(aqs name, the Lua handler function to be registered under that name, and, optionally, the types of artifacts for which the handler may be called. If the latter is not given, the Lua handler is registered for all types of artifacts. The following call registers the above function \fBlua_handler\fP as \fImy_handler\fP which may be called for images: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C swupdate.register_handler("my_handler", lua_handler, swupdate.HANDLER_MASK.IMAGE_HANDLER) .ft P .fi .UNINDENT .UNINDENT .sp A Lua handler may call C handlers ("chaining") via the \fBswupdate.call_handler()\fP method. The callable and registered C handlers are available (as keys) in the table \fBswupdate.handler\fP\&. The following Lua code is an example of a simple handler chain\-calling the \fBrawfile\fP C handler: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C function lua_handler(image) if not swupdate.handler["rawfile"] then swupdate.error("rawfile handler not available") return 1 end image.path = "/tmp/destination.path" local err, msg = swupdate.call_handler("rawfile", image) if err ~= 0 then swupdate.error(string.format("Error chaining handlers: %s", msg)) return 1 end return 0 end .ft P .fi .UNINDENT .UNINDENT .sp Note that when chaining handlers and calling a C handler for a different type of artifact than the Lua handler is registered for, the \fBimage\fP table\(aqs values must satisfy the called C handler\(aqs expectations: Consider the above Lua handler being registered for "images" (\fBswupdate.HANDLER_MASK.IMAGE_HANDLER\fP) via the \fBswupdate.register_handler()\fP call shown above. As per the sw\-description\(aqs attribute reference, the "images" artifact type doesn\(aqt have the \fBpath\fP attribute but the "file" artifact type does. So, for calling the \fBrawfile\fP handler, \fBimage.path\fP has to be set prior to chain\-calling the \fBrawfile\fP handler, as done in the example above. Usually, however, no such adaptation is necessary if the Lua handler is registered for handling the type of artifact that \fBimage\fP represents. .sp In addition to calling C handlers, the \fBimage\fP table passed as parameter to a Lua handler has a \fBimage:copy2file()\fP method that implements the common use case of writing the input stream\(aqs data to a file, which is passed as this method\(aqs argument. On success, \fBimage:copy2file()\fP returns \fB0\fP or \fB\-1\fP plus an error message on failure. The following Lua code is an example of a simple handler calling \fBimage:copy2file()\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C function lua_handler(image) local err, msg = image:copy2file("/tmp/destination.path") if err ~= 0 then swupdate.error(string.format("Error calling copy2file: %s", msg)) return 1 end return 0 end .ft P .fi .UNINDENT .UNINDENT .sp Beyond using \fBimage:copy2file()\fP or chain\-calling C handlers, the \fBimage\fP table passed as parameter to a Lua handler has a \fBimage:read()\fP method that reads from the input stream and calls the Lua callback function \fB\fP for every chunk read, passing this chunk as parameter. On success, \fB0\fP is returned by \fBimage:read()\fP\&. On error, \fB\-1\fP plus an error message is returned. The following Lua code is an example of a simple handler printing the artifact\(aqs content: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C function lua_handler(image) err, msg = image:read(function(data) print(data) end) if err ~= 0 then swupdate.error(string.format("Error reading image: %s", msg)) return 1 end return 0 end .ft P .fi .UNINDENT .UNINDENT .sp Using the \fBimage:read()\fP method, an artifact\(aqs contents may be (post\-)processed in and leveraging the power of Lua without relying on preexisting C handlers for the purpose intended. .sp Just as C handlers, a Lua handler must consume the artifact described in its \fBimage\fP parameter so that SWUpdate can continue with the next artifact in the stream after the Lua handler returns. Chaining handlers, calling \fBimage:copy2file()\fP, or using \fBimage:read()\fP satisfies this requirement. .sp Note that although the dynamic nature of Lua handlers would technically allow one to embed them into a to be processed \fB\&.swu\fP image, this is not implemented as it carries some security implications since the behavior of SWUpdate is changed dynamically. .SS Remote handler .sp Remote handlers are thought for binding legacy installers without having the necessity to rewrite them in Lua. The remote handler forward the image to be installed to another process, waiting for an acknowledge to be sure that the image is installed correctly. The remote handler makes use of the zeromq library \- this is to simplify the IPC with Unix Domain Socket. The remote handler is quite general, describing in sw\-description with the "data" attribute how to communicate with the external process. The remote handler always acts as client, and try a connect() using the socket identified by the "data" attribute. For example, a possible setup using a remote handler could be: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C images: ( { filename = "myimage""; type = "remote"; data = "test_remote"; } ) .ft P .fi .UNINDENT .UNINDENT .sp The connection is instantiated using the socket "/tmp/test_remote". If connect() fails, the remote handler signals that the update is not successful. Each Zeromq Message from SWUpdate is a multi\-part message split into two frames: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 first frame contains a string with a command. .IP \(bu 2 second frame contains data and can be of 0 bytes. .UNINDENT .UNINDENT .UNINDENT .sp There are currently just two possible commands: INIT and DATA. After a successful connect, SWUpdate sends the initialization string in the format: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C INIT: .ft P .fi .UNINDENT .UNINDENT .sp The external installer is informed about the size of the image to be installed, and it can assign resources if it needs. It will answer with the string \fIACK\fP or \fINACK\fP\&. The first NACK received by SWUpdate will interrupt the update. After sending the INIT command, the remote handler will send a sequence of \fIDATA\fP commands, where the second frame in message will contain chunks of the image to be installed. It is duty of the external process to take care of the amount of data transferred and to release resources when the last chunk is received. For each DATA message, the external process answers with a \fIACK\fP or \fINACK\fP message. .SS SWU forwarder .sp The SWU forwarder handler can be used to update other systems where SWUpdate is running. It can be used in case of master / slaves systems, where the master is connected to the network and the "slaves" are hidden to the external world. The master is then the only interface to the world. A general SWU can contain embedded SWU images as single artifacts, and the SWU handler will forward it to the devices listed in the description of the artifact. The handler can have a single "url" properties entry with an array of urls. Each url is the address of a secondary board where SWUpdate is running with webserver activated. The SWU handler expects to talk with SWUpdate\(aqs embedded webserver. This helps to update systems where an old version of SWUpdate is running, because the embedded webserver is a common feature present in all versions. The handler will send the embedded SWU to all URLs at the same time, and setting \fBinstalled\-directly\fP is supported by this handler. [image] .sp The following example shows how to set a SWU as artifact and enables the SWU forwarder: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C images: ( { filename = "image.swu"; type = "swuforward"; properties: { url = ["http://192.168.178.41:8080", "http://192.168.178.42:8080"]; }; }); .ft P .fi .UNINDENT .UNINDENT .SS rdiff handler .sp The rdiff handler adds support for applying binary delta patches generated by \fI\%librsync\(aqs\fP rdiff tool. .sp Naturally, the smaller the difference between the diff\(aqs source and target, the more effective is using this handler rather than shipping the full target, e.g., via the image handler. Hence, the most prominent use case for the rdiff handler is when having a read\-only root filesystem and applying a small update like security fixes or feature additions. If the sweet spot is crossed, an rdiff patch may even exceed the full target\(aqs size due to necessary patch metadata. Also note that in order to be most effective, an image to be processed with rdiff should be built deterministic (see \fI\%reproducible\-builds.org\fP). .sp The rdiff algorithm requires no resources whatsoever on the device as the patch is fully computed in the backend. Consequently, the backend has to have knowledge of the current software running on the device in order to compute a sensible patch. Alike, the patch has to be applied on the device to an unmodified source as used in the backend for patch computation. This property is in particular useful for resource\-constrained devices as there\(aqs no need for the device to, e.g., aid in the difference computation. .sp First, create the signature of the original (base) file via \fBrdiff signature \fP\&. Then, create the delta file (i.e., patch) from the original base file to the target file via \fBrdiff delta \fP\&. The \fB\fP is the artifact to be applied via this handler on the device. Essentially, it mimics running \fBrdiff patch \fP on the device. Naturally for patches, the very same \fB\fP has to be used for creating as well as for applying the patch to. .sp This handler registers itself for handling files and images. An exemplary sw\-description fragment for the files section is .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C files: ( { type = "rdiff_file" filename = "file.rdiff.delta"; path = "/usr/bin/file"; } ); .ft P .fi .UNINDENT .UNINDENT .sp Note that the file referenced to by \fBpath\fP serves as \fB\fP and gets replaced by a temporary file serving as \fB\fP while the rdiff patch processing. .sp An exemplary sw\-description fragment for the images section is .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C images: ( { type = "rdiff_image"; filename = "image.rdiff.delta"; device = "/dev/mmcblk0p2"; properties: { rdiffbase = ["/dev/mmcblk0p1"]; }; } ); .ft P .fi .UNINDENT .UNINDENT .sp Here, the property \fBrdiffbase\fP qualifies the \fB\fP while the \fBdevice\fP attribute designates the \fB\fP\&. Note that there\(aqs no support for the optional \fBoffset\fP attribute in the \fBrdiff_image\fP handler as there\(aqs currently no apparent use case for it and skipping over unchanged content is handled well by the rdiff algorithm. .SS ucfw handler .sp This handler allows one to update the firmware on a microcontroller connected to the main controller via UART. Parameters for setup are passed via sw\-description file. Its behavior can be extended to be more general. The protocol is ASCII based. There is a sequence to be done to put the microcontroller in programming mode, after that the handler sends the data and waits for an ACK from the microcontroller. .sp The programming of the firmware shall be: .INDENT 0.0 .IP 1. 3 Enter firmware update mode (bootloader) .INDENT 3.0 .INDENT 3.5 .INDENT 0.0 .IP 1. 3 Set "reset line" to logical "low" .IP 2. 3 Set "update line" to logical "low" .IP 3. 3 Set "reset line" to logical "high" .UNINDENT .UNINDENT .UNINDENT .IP 2. 3 Send programming message .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $PROG;<> .ft P .fi .UNINDENT .UNINDENT .sp to the microcontroller. (microcontroller will remain in programming state) .INDENT 0.0 .IP 3. 3 microcontroller confirms with .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $READY;<> .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP 4. 3 Data transmissions package based from mainboard to microcontroller package definition: .INDENT 3.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 within a package the records are sent one after another without the end of line marker .IP \(bu 2 the package is completed with .UNINDENT .UNINDENT .UNINDENT .IP 5. 3 The microcontroller requests the next package with $READY;<> .IP 6. 3 Repeat step 4 and 5 until the complete firmware is transmitted. .IP 7. 3 The keypad confirms the firmware completion with $COMPLETED;<> .IP 8. 3 .INDENT 3.0 .TP .B Leave firmware update mode .INDENT 7.0 .IP 1. 3 Set "Update line" to logical "high" .IP 2. 3 Perform a reset over the "reset line" .UNINDENT .UNINDENT .UNINDENT .sp <> : checksum. The checksum is calculated as the two\(aqs complement of the modulo\-256 sum over all bytes of the message string except for the start marker "$". The handler expects to get in the properties the setup for the reset and prog gpios. They should be in this format: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C properties = { reset = "::"; prog = "::"; } .ft P .fi .UNINDENT .UNINDENT .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C images: ( { filename = "microcontroller\-image"; type = "ucfw"; device = "/dev/ttymxc5"; properties: { reset = "/dev/gpiochip0:38:false"; prog = "/dev/gpiochip0:39:false"; }; } ); .ft P .fi .UNINDENT .UNINDENT .SS SSBL Handler .sp This implements a way to switch two software sets using a duplicated structure saved on the flash (currently, only NOR flash is supported). Each of the two structures contains address and size of the image to be loaded by a first loader. A field contain the "age", and it is incremented after each switch to show which is the active set. .SS Structure of SSBL Admin .TS center; |l|l|. _ T{ SSBL Magic Number (29 bit)Name T} T{ Age (3 bit) T} _ T{ Image Address Offset T} _ T{ Image Size T} _ .TE .sp The handler implements a post install script. First, it checks for consistency the two structures and find the active reading the first 32 bit value with a magic number and the age. It increments the age and saves the new structure in the inactive copy. After a reboot, the loader will check it and switch the software set. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C scripts: ( { type = "ssblswitch"; properties: { device = ["mtdX", "mtdY"]; offset = ["0", "0"]; imageoffs = ["0x780000", "0xA40000"]; imagesize = ["0x800000", "0x800000"]; } } .ft P .fi .UNINDENT .UNINDENT .sp Properties in sw\-description are all mandatory. They define where the SSBL Administration data are stored for both sets. Each properties is an array of two entries, containing values for each of the two SSBL administration. .SS Properties for SSBL handler .TS center; |l|l|l|. _ T{ Name T} T{ Type T} T{ Description T} _ T{ device T} T{ string T} T{ MTD device where the SSBL Admin Header is stored T} _ T{ offset T} T{ hex T} T{ Offset of SSBL header inside the MTD device T} _ T{ imageoffset T} T{ hex T} T{ Offset of the image to be loaded by a bootloader when this SSBL is set. T} _ T{ imagesize T} T{ hex T} T{ Size of the image to be loaded by a bootloader when this SSBL is set. T} _ .TE .SS Readback Handler .sp To verify that an image was written properly, this readback handler calculates the sha256 hash of a partition (or part of it) and compares it against a given hash value. .sp The following example explains how to use this handler: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C scripts: ( { device = "/dev/mmcblk2p1"; type = "readback"; properties: { sha256 = "e7afc9bd98afd4eb7d8325196d21f1ecc0c8864d6342bfc6b6b6c84eac86eb42"; size = "184728576"; offset = "0"; }; } ); .ft P .fi .UNINDENT .UNINDENT .sp Properties \fBsize\fP and \fBoffset\fP are optional, all the other properties are mandatory. .SS Properties for readback handler .TS center; |l|l|l|. _ T{ Name T} T{ Type T} T{ Description T} _ T{ device T} T{ string T} T{ The partition which shall be verified. T} _ T{ type T} T{ string T} T{ Identifier for the handler. T} _ T{ sha256 T} T{ string T} T{ Expected sha256 hash of the partition. T} _ T{ size T} T{ string T} T{ Data size (in bytes) to be verified. If 0 or not set, the handler will get the partition size from the device. T} _ T{ offset T} T{ string T} T{ Offset (in bytes) to the start of the partition. If not set, default value 0 will be used. T} _ .TE .SS Disk partitioner .sp This handler creates or modifies partitions using the library libfdisk. Handler must be put into the \fIpartitions\fP section of sw\-description. Setup for each partition is put into the \fIproperties\fP field of sw\-description. .SS Properties for diskpart handler .TS center; |l|l|l|. _ T{ Name T} T{ Type T} T{ Description T} _ T{ labeltype T} T{ string T} T{ "gpt" or "dos" T} _ T{ partition\-X T} T{ array T} T{ Array of values belonging to the partition number X T} _ .TE .sp For each partition, an array of couples key=value must be given. The following keys are supported: .SS Setup for a disk partition .TS center; |l|l|l|. _ T{ Name T} T{ Type T} T{ Description T} _ T{ size T} T{ string T} T{ Size of partition. K, M and G can be used for Kilobytes, Megabytes and Gigabytes. T} _ T{ start T} T{ integer T} T{ First sector for the partition T} _ T{ name T} T{ string T} T{ Name of the partition T} _ T{ type T} T{ string T} T{ Type of partition, it has two different meanings. It is the hex code for DOS (MBR) partition table or it is the string identifier in case of GPT. T} _ .TE .sp GPT example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C partitions: ( { type = "diskpart"; device = "/dev/sde"; properties: { labeltype = "gpt"; partition\-1 = [ "size=64M", "start=2048", "name=bigrootfs", "type=C12A7328\-F81F\-11D2\-BA4B\-00A0C93EC93B"]; partition\-2 = ["size=256M", "start=133120", "name=ldata", "type=EBD0A0A2\-B9E5\-4433\-87C0\-68B6B72699C7"]; partition\-3 = ["size=512M", "start=657408", "name=log", "type=0FC63DAF\-8483\-4772\-8E79\-3D69D8477DE4"]; partition\-4 = ["size=4G", "start=1705984", "name=system", "type=0FC63DAF\-8483\-4772\-8E79\-3D69D8477DE4"]; partition\-5 = ["size=512M", "start=10094592", "name=part5", "type=0FC63DAF\-8483\-4772\-8E79\-3D69D8477DE4"]; } } .ft P .fi .UNINDENT .UNINDENT .sp MBR Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C partitions: ( { type = "diskpart"; device = "/dev/sde"; properties: { labeltype = "dos"; partition\-1 = [ "size=64M", "start=2048", "name=bigrootfs", "type=0x83"]; partition\-2 = ["size=256M", "start=133120", "name=ldata", "type=0x83"]; partition\-3 = ["size=256M", "start=657408", "name=log", "type=0x83"]; partition\-4 = ["size=6G", "start=1181696", "name=system", "type=0x5"]; partition\-5 = ["size=512M", "start=1183744", "name=part5", "type=0x83"]; partition\-6 = ["size=512M", "start=2234368", "name=part6", "type=0x83"]; } } .ft P .fi .UNINDENT .UNINDENT .SS Unique UUID Handler .sp This handler checks if the device already has a filesystems with a provide UUID. This is helpful in case the bootloader chooses the device to boot from the UUID and not from the partition number. One use case is with the GRUB bootloader when GRUB_DISABLE_LINUX_UUID is not set, as usual on Linux Distro as Debian or Ubuntu. .sp The handler iterates all UUIDs given in sw\-description and raises error if one of them is found on the device. It is a partition handler and it runs before any image is installed. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C partitions: ( { type = "uniqueuuid"; properties: { fs\-uuid = ["21f16cae\-612f\-4bc6\-8ef5\-e68cc9dc4380", "18e12df1\-d8e1\-4283\-8727\-37727eb4261d"]; } }); .ft P .fi .UNINDENT .UNINDENT .SH MONGOOSE DAEMON MODE .SS Introduction .sp Mongoose is a daemon mode of SWUpdate that provides a web server, web interface and web application. .sp Mongoose supports two different web interface versions although the first version is deprecated and should not be used. The second version uses a WebSocket for the asynchronous communication between web server and web application, allows a visualization of image update processes, restarts the system via a post update command and automatically reloads the web page after a restart or connection lost. .sp The web application in \fBweb\-app\fP uses the \fI\%Node.js\fP package manager and \fI\%gulp\fP as build tool. It depends on \fI\%Bootstrap 4\fP, \fI\%Font Awesome 5\fP and \fI\%Dropzone.js\fP\&. .SS Startup .sp After having configured and compiled SWUpdate with enabled mongoose web server and web interface version 2 support, .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \&./swupdate \-\-help .ft P .fi .UNINDENT .UNINDENT .sp lists the mandatory and optional arguments to be provided to mongoose. As an example, .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \&./swupdate \-l 5 \-w \(aq\-r ./examples/www/v2 \-p 8080\(aq \-p \(aqreboot\(aq .ft P .fi .UNINDENT .UNINDENT .sp runs SWUpdate in mongoose daemon mode with log\-level \fBTRACE\fP and a web server at \fI\%http://localhost:8080\fP\&. .SS Example .sp The ready to use example of the web application in the \fBexamples/www/v2\fP directory uses a Public Domain \fIbackground.jpg\fP image from \fI\%pixabay\fP with is released under the Creative Commons CC0 license. The used \fIfavicon.png\fP and \fIlogo.png\fP images are made from the SWUpdate logo and therefore subject to the GNU General Public License version 2. You must comply to this license or replace the images with your own files. .SS Customize .sp You could customize the web application inside the \fBweb\-app\fP directory. Beside the replace of the \fIfavicon.png\fP, \fIlogo.png\fP and \fIbackground.jpg\fP images inside the \fBimages\fP directory you could customize the Bootstrap colors and settings inside the \fBscss/bootstrap.scss\fP style sheet. The style sheet changes need a rebuild of the web application source code. .SS Develop .sp The development requires Node.js version 6 or greater and a prebuilt SWUpdate project with enabled mongoose web server and web application interface version 2 support. .INDENT 0.0 .IP 1. 3 Enter the web application directory: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C cd ./web\-app .ft P .fi .UNINDENT .UNINDENT .IP 2. 3 Install the dependencies: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C npm install .ft P .fi .UNINDENT .UNINDENT .IP 3. 3 Build the web application: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C npm run build .ft P .fi .UNINDENT .UNINDENT .IP 4. 3 Start the web application: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C \&../swupdate \-w \(aq\-r ./dist \-p 8080\(aq \-p \(aqecho reboot\(aq .ft P .fi .UNINDENT .UNINDENT .IP 5. 3 Test the web application: .INDENT 3.0 .INDENT 3.5 \fI\%http://localhost:8080/\fP .UNINDENT .UNINDENT .IP 6. 3 Pack the web application (optional): .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C npm run package \-\- \-\-output swupdate\-www.tar.gz .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS Contribute .sp Please run the linter before any commit .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C npm run lint .ft P .fi .UNINDENT .UNINDENT .SH SURICATTA DAEMON MODE .SS Introduction .sp Suricatta is \-\- like mongoose \-\- a daemon mode of SWUpdate, hence the name suricatta (engl. meerkat) as it belongs to the mongoose family. .sp Suricatta regularly polls a remote server for updates, downloads, and installs them. Thereafter, it reboots the system and reports the update status to the server, based on an update state variable currently stored in bootloader\(aqs environment ensuring persistent storage across reboots. Some U\-Boot script logics or U\-Boot\(aqs \fBbootcount\fP feature may be utilized to alter this update state variable, e.g., by setting it to reflect failure in case booting the newly flashed root file system has failed and a switchback had to be performed. .sp Suricatta is designed to be extensible in terms of the servers supported as described in Section \fI\%Supporting different Servers\fP\&. Currently, support for the \fI\%hawkBit\fP server is implemented via the \fI\%hawkBit Direct Device Integration API\fP alongside a simple general purpose HTTP server. .SS Running suricatta .sp After having configured and compiled SWUpdate with enabled suricatta support, .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \&./swupdate \-\-help .ft P .fi .UNINDENT .UNINDENT .sp lists the mandatory and optional arguments to be provided to suricatta when using hawkBit as server. As an example, .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \&./swupdate \-l 5 \-u \(aq\-t default \-u http://10.0.0.2:8080 \-i 25\(aq .ft P .fi .UNINDENT .UNINDENT .sp runs SWUpdate in suricatta daemon mode with log\-level \fBTRACE\fP, polling a hawkBit instance at \fBhttp://10.0.0.2:8080\fP with tenant \fBdefault\fP and device ID \fB25\fP\&. .sp Note that on startup when having installed an update, suricatta tries to report the update status to its upstream server, e.g., hawkBit, prior to entering the main loop awaiting further updates. If this initial report fails, e.g., because of a not (yet) configured network or a currently unavailable hawkBit server, SWUpdate may exit with an according error code. This behavior allows one to, for example, try several upstream servers sequentially. If suricatta should keep retrying until the update status is reported to its upstream server irrespective of the error conditions, this has to be realized externally in terms of restarting SWUpdate on exit. .sp After an update has been performed, an agent listening on the progress interface may execute post\-update actions, e.g., a reboot, on receiving \fBDONE\fP\&. Additionally, a post\-update command specified in the configuration file or given by the \fB\-p\fP command line option can be executed. .sp Note that at least a restart of SWUpdate has to be performed as post\-update action since only then suricatta tries to report the update status to its upstream server. Otherwise, succinct update actions announced by the upstream server are skipped with an according message until a restart of SWUpdate has happened in order to not install the same update again. .SS Supporting different Servers .sp Support for servers other than hawkBit can be realized by implementing the "interfaces" described in \fBinclude/channel.h\fP and \fBinclude/suricatta/server.h\fP\&. The former abstracts a particular connection to the server, e.g., HTTP\-based in case of hawkBit, while the latter implements the logics to poll and install updates. See \fBcorelib/channel_curl.c\fP/\fBinclude/channel_curl.h\fP and \fBsuricatta/server_hawkbit.{c,h}\fP for an example implementation targeted towards hawkBit. .sp \fBinclude/channel.h\fP describes the functionality a channel has to implement: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C typedef struct channel channel_t; struct channel { ... }; channel_t *channel_new(void); .ft P .fi .UNINDENT .UNINDENT .sp which sets up and returns a \fBchannel_t\fP struct with pointers to functions for opening, closing, fetching, and sending data over the channel. .sp \fBinclude/suricatta/server.h\fP describes the functionality a server has to implement: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C server_op_res_t server_has_pending_action(int *action_id); server_op_res_t server_install_update(void); server_op_res_t server_send_target_data(void); unsigned int server_get_polling_interval(void); server_op_res_t server_start(const char *cfgfname, int argc, char *argv[]); server_op_res_t server_stop(void); server_op_res_t server_ipc(int fd); .ft P .fi .UNINDENT .UNINDENT .sp The type \fBserver_op_res_t\fP is defined in \fBinclude/suricatta/suricatta.h\fP\&. It represents the valid function return codes for a server\(aqs implementation. .sp In addition to implementing the particular channel and server, the \fBsuricatta/Config.in\fP file has to be adapted to include a new option so that the new implementation becomes selectable in SWUpdate\(aqs configuration. In the simplest case, adding an option like the following one for hawkBit into the \fBmenu "Server"\fP section is sufficient. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C config SURICATTA_HAWKBIT bool "hawkBit support" depends on HAVE_LIBCURL depends on HAVE_JSON_C select JSON select CURL help Support for hawkBit server. https://projects.eclipse.org/projects/iot.hawkbit .ft P .fi .UNINDENT .UNINDENT .sp Having included the new server implementation into the configuration, edit \fBsuricatta/Makefile\fP to specify the implementation\(aqs linkage into the SWUpdate binary, e.g., for the hawkBit example implementation, the following lines add \fBserver_hawkbit.o\fP to the resulting SWUpdate binary if \fBSURICATTA_HAWKBIT\fP was selected while configuring SWUpdate. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ifneq ($(CONFIG_SURICATTA_HAWKBIT),) lib\-$(CONFIG_SURICATTA) += server_hawkbit.o endif .ft P .fi .UNINDENT .UNINDENT .SS Support for general purpose HTTP server .sp This is a very simple backend that uses standard HTTP response codes to signal if an update is available. There are closed source backends implementing this interface, but because the interface is very simple interface, this server type is also suitable for implementing an own backend server. .sp The API consists of a GET with Query parameters to inform the server about the installed version. The query string has the format: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C http(s)://?param1=val1¶m2=value2... .ft P .fi .UNINDENT .UNINDENT .sp As examples for parameters, the device can send its serial number, MAC address and the running version of the software. It is duty of the backend to interpret this \- SWUpdate just takes them from the "identify" section of the configuration file and encodes the URL. .sp The server answers with the following return codes: .TS center; |l|l|l|. _ T{ HTTP Code T} T{ Text T} T{ Description T} _ T{ 302 T} T{ Found T} T{ A new software is available at URL in the Location header T} _ T{ 400 T} T{ Bad Request T} T{ Some query parameters are missing or in wrong format T} _ T{ 403 T} T{ Forbidden T} T{ Client certificate not valid T} _ T{ 404 T} T{ Not found T} T{ No update is available for this device T} _ T{ 503 T} T{ Unavailable T} T{ An update is available but server can\(aqt handle another update process now. T} _ .TE .sp Server\(aqs answer can contain the following headers: .TS center; |l|l|l|. _ T{ Header\(aqs name T} T{ Codes T} T{ Description T} _ T{ Retry\-after T} T{ 503 T} T{ Contains a number which tells the device how long to wait until ask the next time for updates. (Seconds) T} _ T{ Content\-MD5 T} T{ 302 T} T{ Contains the checksum of the update file which is available under the url of location header T} _ T{ Location T} T{ 302 T} T{ URL where the update file can be downloaded. T} _ .TE .sp The device can send logging data to the server. Any information is transmitted in a HTTP PUT request with the data as plain string in the message body. The Content\-Type Header need to be set to text/plain. .sp The URL for the logging can be set as separate URL in the configuration file or via \-\-logurl command line parameter: .sp The device sends data in a CSV format (Comma Separated Values). The format is: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C value1,value2,... .ft P .fi .UNINDENT .UNINDENT .sp The format can be specified in the configuration file. A \fIformat\fP For each \fIevent\fP can be set. The supported events are: .TS center; |l|l|. _ T{ Event T} T{ Description T} _ T{ check T} T{ dummy. It could send an event each time the server is polled. T} _ T{ started T} T{ A new software is found and SWUpdate starts to install it T} _ T{ success T} T{ A new software was successfully installed T} _ T{ fail T} T{ Failure by installing the new software T} _ .TE .sp The \fIgeneral server\fP has an own section inside the configuration file. As example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gservice = { url = ....; logurl = ; logevent : ( {event = "check"; format="#2,date,fw,hw,sp"}, {event = "started"; format="#12,date,fw,hw,sp"}, {event = "success"; format="#13,date,fw,hw,sp"}, {event = "fail"; format="#14,date,fw,hw,sp"} ); } .ft P .fi .UNINDENT .UNINDENT .sp \fIdate\fP is a special field and it is interpreted as localtime in RFC 2822 format. Each Comma Separated field is looked up inside the \fIidentify\fP section in the configuration file, and if a match is found the substitution occurs. In case of no match, the field is sent as it is. For example, if the identify section has the following values: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C identify : ( { name = "sp"; value = "333"; }, { name = "hw"; value = "ipse"; }, { name = "fw"; value = "1.0"; } ); .ft P .fi .UNINDENT .UNINDENT .sp with the events set as above, the formatted text in case of "success" will be: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Formatted log: #13,Mon, 17 Sep 2018 10:55:18 CEST,1.0,ipse,333 .ft P .fi .UNINDENT .UNINDENT .SH CONFIG FOR HAWKBIT UNDER SSL/TLS USING PRIVATE CA / SUB CA .sp A user\-contributed recipe based on hawkBit (0.2.0\-SNAPSHOT) + swupdate (v2018.03) .SS Purpose .sp Use HTTPS on a hawkBit server to avoid server spoofing. Anonymous client connections are authorized. .SS Recipe .INDENT 0.0 .IP 1. 3 On the PKI: .UNINDENT .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 Create a pkcs#12 (\fB\&.p12\fP) file, rolling server key, server, private CA, sub CA certs into a single file. .IP \(bu 2 Use a password on the server key you won\(aqt be ashamed of. .IP \(bu 2 Also create a single \fB\&.pem\fP file for the private CA + sub\-CA .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .IP 2. 3 On the hawkBit host: .UNINDENT .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 hawkBit uses the Java KeyStore to access credentials, but a JKS is not designed apparently to hold CA certs, which is a problem for private CAs. The workaround is to make it gulp an entire pkcs#12 file. .IP \(bu 2 It looks like a JKS like this cannot have a password different from the one protecting the \fB\&.p12\fP\&. Keytool also seems to have a little tendency to destruct the \fB\&.jks\fP if you change your mind and want to change the password... Basically do everything you need with openssl and use only keytool for generating the \fB\&.jks\fP file. .UNINDENT .sp The following command imports a \fB\&.p12\fP into a "pkcs12 Java keystore", keeping the same password: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C keytool \-importkeystore \-srckeystore hb\-pass.p12 \-srcstoretype pkcs12 \e \-destkeystore hb\-pass.jks \-deststoretype pkcs12 \e \-alias 1 \-deststorepass .ft P .fi .UNINDENT .UNINDENT .sp Then you need to adapt \fBapplication.properties\fP of the hawkBit server to make use of the keystore. There are extra requirements to make hawkBit send artifacts via HTTPS. .sp This is the relevant part of \fB/hawkbit\-runtime/hawkbit\-update\-server/src/main/resources/application.properties\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # HTTPS mode working w/ swupdate # See also https://docs.spring.io/spring\-boot/docs/1.4.7.RELEASE/reference/html/howto\-embedded\-servlet\-containers.html#howto\-configure\-ssl # https://github.com/eclipse/hawkbit/issues/618 # # Need to run as root to use port 443 server.hostname=hb.domain server.port=8443 # # Overriding some of hawkbit\-artifactdl\-defaults.properties is required hawkbit.artifact.url.protocols.download\-http.protocol=https hawkbit.artifact.url.protocols.download\-http.port=8443 # # Upgrades http:8443 to https:8443 # Would redirect + upgrade http:80 to https:443 security.require\-ssl=true server.use\-forward\-headers=true # # Server cert+key w/ private CA + subCA # See also https://stackoverflow.com/questions/906402/how\-to\-import\-an\-existing\-x509\-certificate\-and\-private\-key\-in\-java\-keystore\-to\-u # http://cunning.sharp.fm/2008/06/importing_private_keys_into_a.html (2008, still relevant!?) # # File .jks is a .p12 imported via keytool. Only one password supported, set from openssl. server.ssl.key\-store=hb\-pass.jks server.ssl.key\-password=password server.ssl.key\-store\-password=password\-yes_the_same_one \&... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .IP 3. 3 On the swupdate client host(s): .UNINDENT .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 The client needs the private CA certificate(s) to authenticate the server. .IP \(bu 2 There is a setting in swupdate to specify the path to a single CA cert, not a directory. Beyond that, libcurl looks into \fB/etc/ssl/certs\fP\&. So we\(aqre using a compound "CA chain" \fB\&.pem\fP file to hold both private CA and sub\-CA in our preferred location. .UNINDENT .sp This is the relevant part of \fB/etc/swupdate/swupdate.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \&... suricatta : { tenant = "default"; id = "machineID"; url = "https://hb.domain:8443"; nocheckcert = false; cafile = "/etc/swupdate/priv\-cachain.pem"; /* CA + sub CA in one file */ /* sslkey = anon client: do not set; */ /* sslcert = anon client: do not set; */ \&... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SH SWUPDATE: API FOR EXTERNAL PROGRAMS .SS Overview .sp SWUpdate contains an integrated web\-server to allow remote updating. However, which protocols are involved during an update is project specific and differs significantly. Some projects can decide to use FTP to load an image from an external server, or using even a proprietary protocol. The integrated web\-server uses this interface. .sp SWUpdate has a simple interface to let external programs to communicate with the installer. Clients can start an upgrade and stream an image to the installer, querying then for the status and the final result. The API is at the moment very simple, but it can easy be extended in the future if new use cases will arise. .SS API Description .sp The communication runs via UDS (Unix Domain Socket). The socket is created at startup by SWUpdate in /tmp/sockinstctrl as per default configuration. This socket should, however, not be used directly but instead by the Client Library explained below. .sp The exchanged packets are described in network_ipc.h .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C typedef struct { int magic; int type; msgdata data; } ipc_message; .ft P .fi .UNINDENT .UNINDENT .sp Where the fields have the meaning: .INDENT 0.0 .IP \(bu 2 magic : a magic number as simple proof of the packet .IP \(bu 2 type : one of REQ_INSTALL, ACK, NACK, GET_STATUS, POST_UPDATE, SWUPDATE_SUBPROCESS, SET_AES_KEY .IP \(bu 2 msgdata : a buffer used by the client to send the image or by SWUpdate to report back notifications and status. .UNINDENT .sp The client sends a REQ_INSTALL packet and waits for an answer. SWUpdate sends back ACK or NACK, if for example an update is already in progress. .sp After the ACK, the client sends the whole image as a stream. SWUpdate expects that all bytes after the ACK are part of the image to be installed. SWUpdate recognizes the size of the image from the CPIO header. Any error lets SWUpdate to leave the update state, and further packets will be ignored until a new REQ_INSTALL will be received. [image] .sp It is recommended to use the client library to communicate with SWUpdate. On the lower level with direct socket communication, it cannot be guaranteed that the structures will remain compatible in future. The client library was affected by this issue, too, and it is changed to accept an opaque interface that will survive to API changes. Compatibility layers could be added on bedarf in future due to API changes. .SS Client Library .SS Functions to start an update .sp A library simplifies the usage of the IPC making available a way to start asynchronously an update. .sp The library consists of one function and several call\-backs. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C int swupdate_async_start(writedata wr_func, getstatus status_func, terminated end_func, void *req, ssize_t size) typedef int (*writedata)(char **buf, int *size); typedef int (*getstatus)(ipc_message *msg); typedef int (*terminated)(RECOVERY_STATUS status); .ft P .fi .UNINDENT .UNINDENT .sp swupdate_async_start creates a new thread and start the communication with SWUpdate, triggering for a new update. The wr_func is called to get the image to be installed. It is responsibility of the callback to provide the buffer and the size of the chunk of data. .sp The getstatus call\-back is called after the stream was downloaded to check how upgrade is going on. It can be omitted if only the result is required. .sp The terminated call\-back is called when SWUpdate has finished with the result of the upgrade. .sp Example about using this library is in the examples/client directory. .sp The \fIreq\fP structure is casted to void to ensure API compatibility. Am user should instantiate it as \fIstruct swupdate_request\fP\&. This contains fields that can control the update process: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C struct swupdate_request { unsigned int apiversion; sourcetype source; int dry_run; size_t len; char info[512]; char software_set[256]; char running_mode[256]; }; .ft P .fi .UNINDENT .UNINDENT .sp A user should first call \fIswupdate_prepare_req()\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C void swupdate_prepare_req(struct swupdate_request *req); .ft P .fi .UNINDENT .UNINDENT .sp This fills the request sturcture with default values. After that, the user can fill the other fields as: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fIsourcetype\fP : one of SOURCE_UNKNOWN, SOURCE_WEBSERVER, SOURCE_SURICATTA, SOURCE_DOWNLOADER, SOURCE_LOCAL .IP \(bu 2 \fIdry_run\fP : one of RUN_DEFAULT (set from command line), RUN_DRYRUN, RUN_INSTALL. .IP \(bu 2 \fIinfo, len\fP : a variable length data that can be forwarded to the progress interface. The installer in SWUpdate does not evaluate it. .IP \(bu 2 \fIsoftware_set\fP and \fIrunning_mode\fP : this allows to set the \fIselection\fP fot the update. .UNINDENT .UNINDENT .UNINDENT .SS Functions to set AES keys .sp The key for decryption can be set with command line parameter (see \fI\-K\fP), but it is possible to set it via IPC. In this way, each update could have a different key. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C int swupdate_set_aes(char *key, char *ivt) .ft P .fi .UNINDENT .UNINDENT .sp The key is for AES\-256. The length for key and ivt are then defined by the algorithm amd they are passed as ASCII string, so the length \fImust\fP be 64 bytes for key and 32 bytes for IVT. .SS Functions to control SWUpdate .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C int ipc_send_cmd(ipc_message *msg); .ft P .fi .UNINDENT .UNINDENT .sp ipc_send_cmd is used to send a command to a SWUpdate subprocess (as suricatta). The function is synchron, that means it clocks until the subprocess has answered with ACK or NACK. This function sets \fItype\fP to SWUPDATE_SUBPROCESS. The caller must then set the other fields in message according to the destination. The msgdata field is a structure as: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C struct { sourcetype source; /* Who triggered the update */ int cmd; /* Optional encoded command */ int timeout; /* timeout in seconds if an aswer is expected */ unsigned int len; /* Len of data valid in buf */ char buf[2048]; /* * Buffer that each source can fill * with additional information */ } .ft P .fi .UNINDENT .UNINDENT .sp The caller fills \fIsource\fP with the subprocess that acceps the command. Values of cmd are in \fInetwork_ipc.h\fP\&. .SS Messages for suricatta .sp suricatta accepts messages in JSON format. The message must be formatted in the \fIbuf\fP field of the message data. .SS Setting the polling time .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "polling" : } .ft P .fi .UNINDENT .UNINDENT .sp Setting it to 0 has the special meaning that the polling time is retrieved from the Backend (if this is supported by the server). .SS Enable / disable Suricatta daemon .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "enable" : true } { "enable" : false } .ft P .fi .UNINDENT .UNINDENT .SS Trigger a check on the server .sp This is useful in case the device is mostly offline, and when it is online, it should check immediately if an update exists and run it. In fact, after enabling the suricatta daemon, the update follows the usual states, and the daemon waits for a polling time before loading the new software. This command forces an update (if available) without changing the polling time. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "trigger" : true } .ft P .fi .UNINDENT .UNINDENT .SS Activate an already installed Software .sp After a software was installed, the new software boots and if everything runs fine, an acknowledge should be sent to the hawkBit server. If this feature is used, for example to let the end user decide if the new software is accepted, the paramters used by the installation should be stored during the update process. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "id" : , "finished" : "success", "failure", "none", "execution" : ["closed", "proceeding", canceled", "rejected", "resumed"] "details" : [ ] } .ft P .fi .UNINDENT .UNINDENT .SS API to the integrated Webserver .sp The integrated Webserver provides REST resources to push a SWU package and to get inform about the update process. This API is based on HTTP standards. There are to kind of interface: .INDENT 0.0 .IP \(bu 2 Install API to push a SWU and to restart the device after update. .IP \(bu 2 A WebSocket interface to send the status of the update process. .UNINDENT .SS Install API .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C POST /upload .ft P .fi .UNINDENT .UNINDENT .sp This initiates an update: the initiator sends the request and start to stream the SWU in the same way as described in \fI\%API Description\fP\&. .SS Restart API .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C POST /restart .ft P .fi .UNINDENT .UNINDENT .sp If configured (see post update command), this request will restart the device. .SS WebSocket API .sp The integrated Webserver exposes a WebSocket API. The WebSocket protocol specification defines ws (WebSocket) and wss (WebSocket Secure) as two new uniform resource identifier (URI) schemes that are used for unencrypted and encrypted con nections, respectively and both of them are supported by SWUpdate. A WebSocket provides full\-duplex communication but it is used in SWUpdate to send events to an external host after each change in the update process. The Webserver sends JSON formatted responses as results of internal events. .sp The response contains the field type, that defines which event is sent. .SS Event Type .TS center; |l|l|. _ T{ type T} T{ Description of event T} _ T{ status T} T{ Event sent when SWUpdate\(aqs internal state changes T} _ T{ source T} T{ Event to inform from which interface an update is received T} _ T{ info T} T{ Event with custom message to be passed to an external process T} _ T{ message T} T{ Event that contains the error message in case of error T} _ T{ step T} T{ Event to inform about the running update T} _ .TE .SS Status Change Event .sp This event is sent when the internal SWUpdate status change. Following status are supported: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C IDLE START RUN SUCCESS .ft P .fi .UNINDENT .UNINDENT .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "type": "status", "status": "SUCCESS" } .ft P .fi .UNINDENT .UNINDENT .SS Source Event .sp This event informs from which interface a SWU is loaded. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "type": "source", "source": "WEBSERVER" } .ft P .fi .UNINDENT .UNINDENT .sp The field \fIsource\fP can have one of the following values: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C UNKNOWN WEBSERVER SURICATTA DOWNLOADER LOCAL .ft P .fi .UNINDENT .UNINDENT .SS Info Event .sp This event forwards all internal logs sent with level=INFO. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "type": "info", "source": < text message > } .ft P .fi .UNINDENT .UNINDENT .SS Message Event .sp This event contains the error message in case of failure. .SS Fields for message event .TS center; |l|l|. _ T{ name T} T{ Description T} _ T{ status T} T{ "message" T} _ T{ level T} T{ "3" in case of error, "6" as info T} _ T{ text T} T{ Message associated to the event T} _ .TE .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "type": "message", "level": "3", "text" : "[ERROR] : SWUPDATE failed [0] ERROR core/cpio_utils.c : ", } .ft P .fi .UNINDENT .UNINDENT .SS Step event .sp This event contains which is the current step running and which percentage of this step is currently installed. .SS Fields for step event .TS center; |l|l|. _ T{ name T} T{ Description T} _ T{ number T} T{ total number of steps N for this update T} _ T{ step T} T{ running step in range [1..N] T} _ T{ name T} T{ filename of artefact to be installed T} _ T{ percent T} T{ percentage of the running step T} _ .TE .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "type": "step", "number": "7", "step": "2", "name": "rootfs.ext4.gz", "percent": "18" } .ft P .fi .UNINDENT .UNINDENT .SH GETTING INFORMATION ON RUNNING UPDATE .sp It is often required to inform the operator about the status of the running update and not just to return if the update was successful or not. For example, if the target has a display or a remote interface, it can be forwarded which is reached percentage of the update to let estimate how much the update will still run. SWUpdate has an interface for this ("progress API"). An external process can register itself with SWUpdate, and it will receive notifications when something in the update was changed. This is different from the IPC API, because the last one is mainly used to transfer the SWU image, and it is only possible to poll the interface to know if the update is still running. .SS API Description .sp An external process registers itself to SWUpdate with a connect() request to the domain socket "/tmp/swupdateprog" as per default configuration of SWUpdate. There is no information to send, and SWUpdate simply inserts the new connection into the list of processes to be informed. SWUpdate will send a frame back after any change in the update process with the following data (see include/progress_ipc.h): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C struct progress_msg { unsigned int magic; /* Magic Number */ unsigned int status; /* Update Status (Running, Failure) */ unsigned int dwl_percent; /* % downloaded data */ unsigned int nsteps; /* No. total of steps */ unsigned int cur_step; /* Current step index */ unsigned int cur_percent; /* % in current step */ char cur_image[256]; /* Name of image to be installed */ char hnd_name[64]; /* Name of running handler */ sourcetype source; /* Interface that triggered the update */ unsigned int infolen; /* Len of data valid in info */ char info[2048]; /* additional information about install */ }; .ft P .fi .UNINDENT .UNINDENT .sp The single fields have the following meaning: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fImagic\fP is not yet used, it could be added for simply verification of the frame. .IP \(bu 2 \fIstatus\fP is one of the values in swupdate_status.h (START, RUN, SUCCESS, FAILURE, DOWNLOAD, DONE). .IP \(bu 2 \fIdwl_percent\fP is the percentage of downloaded data when status = DOWNLOAD. .IP \(bu 2 \fInsteps\fP is the total number of installers (handlers) to be run. .IP \(bu 2 \fIcur_step\fP is the index of the running handler. cur_step is in the range 1..nsteps .IP \(bu 2 \fIcur_percent\fP is the percentage of work done inside the current handler. This is useful when updating a slow interface, such as a slow flash, and signals which is the percentage of image already copied into the destination. .IP \(bu 2 \fIcur_image\fP is the name of the image in sw\-description that is currently being installed. .IP \(bu 2 \fIhnd_name\fP reports the name of the running handler. .IP \(bu 2 \fIsource\fP is the interface that triggered the update. .IP \(bu 2 \fIinfolen\fP length of data in the following info field. .IP \(bu 2 \fIinfo\fP additional information about installation. .UNINDENT .UNINDENT .UNINDENT .sp As an example for a progress client, \fBtools/progress.c\fP prints the status on the console and drives "psplash" to draw a progress bar on a display. .SH LANGUAGE BINDINGS .SS Overview .sp In general, SWUpdate is agnostic to a particular language it is operated from, thanks to SWUpdate\(aqs socket\-based control and progress APIs for external programs. As long as the language of choice has proper socket (library) support, SWUpdate can be operated with it. .sp However, for convenience, a Lua language binding in terms of a shared library, currently \fBlua_swupdate.so.0.1\fP, is provided. .SS Lua Language Binding .sp The Lua language binding is realized in terms of the \fBswupdate\fP module that defines three bindings, namely for the control interface, the progress interface, and a convenience function yielding a table holding all local network interfaces including their IP addresses and submasks. .sp Note that, depending on the filesystem location of the Lua binding\(aqs shared library, Lua\(aqs \fBpackage.cpath\fP may have to be adapted by setting the environment variable \fBLUA_CPATH\fP, modifying \fBpackage.cpath\fP prior to a \fBrequire(\(aqlua_swupdate\(aq)\fP, or , as last resort, using \fBpackage.loadlib()\fP instead of \fBrequire(\(aqlua_swupdate\(aq)\fP\&. .SS Control Interface .sp The \fBswupdate\fP module\(aqs control interface binding conveniently makes SWUpdate\(aqs socket\-based control API available to pure Lua. .sp The binding is captured in the \fBswupdate_control\fP object that is returned by a call to \fBswupdate.control()\fP\&. This object offers the three methods \fBconnect()\fP, \fBwrite()\fP, and \fBclose()\fP: .sp The \fBconnect()\fP method initializes the connection to SWUpdate\(aqs control socket, sends \fBREQ_INSTALL\fP, and waits for \fBACK\fP or \fBNACK\fP, returning the socket connection file descriptor, mostly for information purposes, or, in case of an error, \fBnil\fP plus an error message. .sp The artifact\(aqs data can then be sent to SWUpdate via the \fBwrite()\fP method, returning \fBtrue\fP, or, in case of errors, \fBnil\fP plus an error message. .sp Finally, the \fBclose()\fP method closes the connection to SWUpdate\(aqs control socket after which it waits for SWUpdate to complete the update transaction and executes the post\-install command, if given. .sp The following example snippet illustrates how to use the control interface binding: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C local artifact = io.open("/some/path/to/artifact.swu", "rb" ) swupdate = require(\(aqlua_swupdate\(aq) local ctrl = swupdate.control() if not ctrl:connect() then \-\- Deliberately neglecting error message. io.stderr:write("Error connecting to SWUpdate control socket.\en") return end while true do local chunk = artifact:read(1024) if not chunk then break end if not ctrl:write(chunk) then \-\- Deliberately neglecting error message. io.stderr:write("Error writing to SWUpdate control socket.\en") break end end local res, msg = ctrl:close() if not res then io.stderr:write(string.format("Error finalizing update: %s\en", msg)) end .ft P .fi .UNINDENT .UNINDENT .SS Progress Interface .sp The \fBswupdate\fP module\(aqs progress interface binding conveniently makes SWUpdate\(aqs socket\-based progress API available to pure Lua. .sp The binding is captured in the \fBswupdate_progress\fP object that is returned by a call to \fBswupdate.progress()\fP\&. This object offers the three methods \fBconnect()\fP, \fBreceive()\fP, and \fBclose()\fP: .sp The \fBconnect()\fP method connects to SWUpdate\(aqs progress socket, waiting until the connection has been established. Note that it is only really required to explicitly call \fBconnect()\fP to reestablish a broken connection as the \fBswupdate_progress\fP object\(aqs instantiation already initiates the connection. .sp The \fBreceive()\fP method returns a table representation of the \fBstruct progress_msg\fP described in the progress interface\(aqs API description\&. .sp The \fBclose()\fP method deliberately closes the connection to SWUpdate\(aqs progress socket. .SS IPv4 Interface .sp For convenience, the \fBswupdate\fP module provides the \fBipv4()\fP method returning a table holding the local network interfaces as the table\(aqs keys and their space\-separated IP addresses plus subnet masks as respective values. .SH META-SWUPDATE: BUILDING WITH YOCTO .SS Overview .sp The \fI\%Yocto\-Project\fP is a community project under the umbrella of the Linux Foundation that provides tools and template to create the own custom Linux\-based software for embedded systems. .sp Add\-on features can be added using \fIlayers\fP\&. \fI\%meta\-swupdate\fP is the layer to cross\-compile the SWUpdate application and to generate the compound SWU images containing the release of the product. It contains the required changes for mtd\-utils and for generating Lua. Using meta\-SWUpdate is a straightforward process. As described in Yocto\(aqs documentation about layers, you should include it in your \fIbblayers.conf\fP file to use it. .sp Add meta\-SWUpdate as usual to your bblayers.conf. You have also to add meta\-oe to the list. .sp In meta\-SWUpdate there is a recipe to generate an initrd with a rescue system with SWUpdate. Use: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C MACHINE= bitbake swupdate\-image .ft P .fi .UNINDENT .UNINDENT .sp You will find the result in your tmp/deploy/ directory. How to install and start an initrd is very target specific \- please check in the documentation of your bootloader. .SS What about libubootenv ? .sp This is a common issue when SWUpdate is built. SWUpdate depends on this library, that is generated from the U\-Boot\(aqs sources. This library allows one to safe modify the U\-Boot environment. It is not required if U\-Boot is not used as bootloader. If SWUpdate cannot be linked, you are using an old version of U\-Boot (you need at least 2016.05). If this is the case, you can add your own recipe for the package u\-boot\-fw\-utils, adding the code for the library. .sp It is important that the package u\-boot\-fw\-utils is built with the same sources of the bootloader and for the same machine. In fact, the target can have a default environment linked together with U\-Boot\(aqs code, and it is not (yet) stored into a storage. SWUpdate should be aware of it, because it cannot read it: the default environment must be linked as well to SWUpdate\(aqs code. This is done inside the libubootenv. .sp If you build for a different machine, SWUpdate will destroy the environment when it tries to change it the first time. In fact, a wrong default environment is taken, and your board won\(aqt boot again. .sp To avoid possible mismatch, a new library was developed to be hardware independent. A strict match with the bootloader is not required anymore. The meta\-swupdate layer contains recipes to build the new library (\fIlibubootenv\fP) and adjust SWUpdate to be linked against it. To use it as replacement for u\-boot\-fw\-utils: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 set PREFERRED_PROVIDER_u\-boot\-fw\-utils = "libubootenv" .IP \(bu 2 add to SWUpdate config: .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C CONFIG_UBOOT=y CONFIG_UBOOT_NEWAPI=y .ft P .fi .UNINDENT .UNINDENT .sp With this library, you can simply pass the default environment as file (u\-boot\-initial\-env). It is recommended for new project to switch to the new library to become independent from the bootloader. .SS The swupdate class .sp meta\-swupdate contains a class specific for SWUpdate. It helps to generate the SWU image starting from images built inside the Yocto. It requires that all components, that means the artifacts that are part of the SWU image, are present in the Yocto\(aqs deploy directory. This class should be inherited by recipes generating the SWU. The class defines new variables, all of them have the prefix \fISWUPDATE_\fP in the name. .INDENT 0.0 .IP \(bu 2 \fBSWUPDATE_IMAGES\fP : this is a list of the artifacts to be packaged together. The list contains the name of images without any extension for MACHINE or filetype, that are added automatically. Example : .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C SWUPDATE_IMAGES = "core\-image\-full\-cmdline uImage" .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 \fBSWUPDATE_IMAGES_FSTYPES\fP : extension of the artifact. Each artifact can have multiple extension according to the IMAGE_FSTYPES variable. For example, an image can be generated as tarball and as UBIFS for target. Setting the variable for each artifact tells the class which file must be packed into the SWU image. .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C SWUPDATE_IMAGES_FSTYPES[core\-image\-full\-cmdline] = ".ubifs" .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 \fBSWUPDATE_IMAGES_NOAPPEND_MACHINE\fP : flag to use drop the machine name from the artifact file. Most images in \fIdeploy\fP have the name of the Yocto\(aqs machine in the filename. The class adds automatically the name of the MACHINE to the file, but some artifacts can be deployed without it. .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C SWUPDATE_IMAGES_NOAPPEND_MACHINE[my\-image] = "1" .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 \fBSWUPDATE_SIGNING\fP : if set, the SWU is signed. There are 3 allowed values: RSA, CMS, CUSTOM. This value determines used signing mechanism. .IP \(bu 2 \fBSWUPDATE_SIGN_TOOL\fP : instead of using openssl, use SWUPDATE_SIGN_TOOL to sign the image. A typical use case is together with a hardware key. It is available if SWUPDATE_SIGNING is set to CUSTOM .IP \(bu 2 \fBSWUPDATE_PRIVATE_KEY\fP : this is the file with the private key used to sign the image using RSA mechanism. Is available if SWUPDATE_SIGNING is set to RSA. .IP \(bu 2 \fBSWUPDATE_PASSWORD_FILE\fP : an optional file containing the password for the private key. It is available if SWUPDATE_SIGNING is set to RSA. .IP \(bu 2 \fBSWUPDATE_CMS_KEY\fP : this is the file with the private key used in signing process using CMS mechanism. It is available if SWUPDATE_SIGNING is set to CMS. .IP \(bu 2 \fBSWUPDATE_CMS_CERT\fP : this is the file with the certificate used in signing process using using CMS method. It is available if SWUPDATE_SIGNING is set to CMS. .IP \(bu 2 \fBSWUPDATE_AES_FILE\fP : this is the file with the AES password to encrypt artifact. A new \fIfstype\fP is supported by the class (type: \fIenc\fP). SWUPDATE_AES_FILE is generated as output from openssl to create a new key with .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C openssl enc \-aes\-256\-cbc \-k \-P \-md sha1 > $SWUPDATE_AES_FILE .ft P .fi .UNINDENT .UNINDENT .sp To use it, it is enough to add IMAGE_FSTYPES += "enc" to the artifact. SWUpdate supports decryption of compressed artifact, such as .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C IMAGE_FSTYPES += ".ext4.gz.enc" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS Automatic sha256 in sw\-description .sp The swupdate class takes care of computing and inserting sha256 hashes in the sw\-description file. The attribute \fIsha256\fP \fBmust\fP be set in case the image is signed. Each artifact must have the attribute: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sha256 = "@artifact\-file\-name" .ft P .fi .UNINDENT .UNINDENT .sp For example, to add sha256 to the standard Yocto core\-image\-full\-cmdline: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sha256 = "@core\-image\-full\-cmdline\-machine.ubifs"; .ft P .fi .UNINDENT .UNINDENT .sp The name of the file must be the same as in deploy directory. .SS BitBake variable expansion in sw\-description .sp To insert the value of a BitBake variable into the update file, pre\- and postfix the variable name with "@@". For example, to automatically set the version tag: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C version = "@@DISTRO_VERSION@@"; .ft P .fi .UNINDENT .UNINDENT .SS Template for recipe using the class .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C DESCRIPTION = "Example recipe generating SWU image" SECTION = "" LICENSE = "" # Add all local files to be added to the SWU # sw\-description must always be in the list. # You can extend with scripts or wahtever you need SRC_URI = " \e file://sw\-description \e " # images to build before building swupdate image IMAGE_DEPENDS = "core\-image\-full\-cmdline virtual/kernel" # images and files that will be included in the .swu image SWUPDATE_IMAGES = "core\-image\-full\-cmdline uImage" # a deployable image can have multiple format, choose one SWUPDATE_IMAGES_FSTYPES[core\-image\-full\-cmdline] = ".ubifs" SWUPDATE_IMAGES_FSTYPES[uImage] = ".bin" inherit swupdate .ft P .fi .UNINDENT .UNINDENT .SH SWUPDATE-CLIENT .sp swupdate\-client is a small tool that sends a SWU image to a running instance of SWUpdate. It can be used if the update package (SWU) is downloaded by another application external to SWUpdate. It is an example how to use the IPC to forward an image to SWUpdate. .SS SYNOPSIS .sp swupdate\-client [OPTIONS] ... .SS DESCRIPTION .INDENT 0.0 .TP .B \-h print help and exit .TP .B \-d ask the server to only perform a dry\-run .TP .B \-q go quiet, resets verbosity .TP .B \-v go verbose, essentially print upgrade status messages from server .TP .B \-p ask the server to run post\-update commands if upgrade succeeds .UNINDENT .SH SWUPDATE-HAWKBITCFG .sp swupdate\-hawkbitcfg is a small tool that tries to connect to a running instance of SWUpdate and configures hawkBit\(aqs parameter. .SS SYNOPSIS .sp swupdate\-hawkbitcfg [option] .SS DESCRIPTION .INDENT 0.0 .TP .B \-h help .TP .B \-p allows to set the polling time (in seconds) .TP .B \-e enable suricatta mode .TP .B \-d disable suricatta mode .UNINDENT .SH SWUPDATE-SENDTOHAWKBIT .sp swupdate\-sendtohawkbit is a small tool that tries to connect to a running instance of SWUpdate and uses it as proxy to send data to the hawkBit Server. A typical use case is acknowledgement for activation by an application or operator after a new software has been installed. The tool can forward the result for the activation to the hawkBit server. .SS SYNOPSIS .sp swupdate\-sendtohawkbit .. .SS DESCRIPTION .sp See hawkBit API to get more information on the parameters. .SH SWUPDATE-PROGRESS .sp swupdate\-progress tries to connect to a running instance of SWUpdate to get the status of a running update. .SS SYNOPSIS .sp swupdate\-progress [option] .SS DESCRIPTION .sp swupdate\-progress is an example how to connect to SWUpdate via the progress interface. It shows on stdout a simple bar with the percent indication of the current update and reports the result of the update. It can optionally drive "psplash" or execute a script after an update. .INDENT 0.0 .TP .B \-c Use colors to show results on stdout .TP .B \-e Command to be execute after an update .TP .B \-p send percentage to psplash .TP .B \-r optionally reboot the target after a successful update .TP .B \-s path to progress IPC socket in case the default is not taken .TP .B \-w waits for a SWUpdate connection instead of exit with error .TP .B \-h print a help .UNINDENT .SH SWUPDATE-SYSRESTART .sp swupdate\-sysrestart is a restart controller. It checks the update status and in case of success, it reboots all devices that were updated. .SS SYNOPSIS .sp swupdate\-sysrestart [option] .SS DESCRIPTION .INDENT 0.0 .TP .B \-r optionally reboot the target after a successful update .TP .B \-w waits for a SWUpdate connection instead of exit with error .TP .BI \-s \ path to progress IPC socket .UNINDENT .SH HELP AND SUPPORT .SS Mailing List .sp There is a mailing list for this project: .INDENT 0.0 .INDENT 3.5 \fI\%swupdate@googlegroups.com\fP .UNINDENT .UNINDENT .sp Issue related to the project or to the documentation are discussed here. .SS SWUpdate Flyer .sp A short description about the project and the features (in English and German) can be found in the \fI\%flyer\fP .SS Workshop and SWUpdate integration in project .sp For quick integration of SWUpdate in your project, you could be interested in the \fI\%Training\fP .SS Commercial support and board integration .sp Please check for \fIservices \fP if you need professional support or you need help to get SWUpdate on your device. .SS Talks about SWUpdate .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fI\%Software Update in Embedded Systems by Stefano Babic\fP .IP \(bu 2 \fI\%Updating Embedded Linux devices in field by Chris Simmonds\fP .IP \(bu 2 \fI\%OpenEmbedded in the Real World by Scott Murray\fP .IP \(bu 2 \fI\%[RFC] Device\-side support for software update in AGL by Matt Porter\fP .IP \(bu 2 \fI\%Open Source secure software updates for Linux\-based IVI systems by Arthur Taylor\fP .IP \(bu 2 \fI\%How do you update your embedded Linux devices? by Daniel Sangorrin / Keijiro Yano\fP .IP \(bu 2 \fI\%Comparison of Linux Software Update Technologies by Matt Porter\fP .IP \(bu 2 Software update for IoT: the current state of play by Chris Simmonds, ELCE 2016, \fI\%Slides\fP, \fI\%Video\fP .IP \(bu 2 OSS Remote Firmware Updates for IoT\-like Projects by Silvano Cirujano Cuesta, ELCE 2016, \fI\%Slides ELCE 2016\fP, \fI\%Video ELCE 2016\fP .IP \(bu 2 System Upgrade with SWUpdate by Gabriel Huau, ELC 2017, \fI\%Slides ELC 2017\fP, \fI\%Video ELC 2017\fP .IP \(bu 2 \fI\%BoF: Secure OTA Collaboration, by Ricardo Salveti and Alan Bennett, ELCE 2017\fP .IP \(bu 2 Orchestrated Android\-Style System Upgrades for Embedded Linux by Diego Rondini, ELCE 2017, \fI\%Slides Android\-Style\fP, \fI\%Video Android\-Style\fP .IP \(bu 2 Updating an Embedded System with SWUpdate Framework by Stefano Babic, ELCE 2017, \fI\%Slides ELCE 2017\fP, \fI\%Video ELCE 2017\fP .IP \(bu 2 Upgrading buildroot based devices with SWUpdate by Angelo Compagnucci, LinuxLab 2018, \fI\%Slides LinuxLab 2018\fP, \fI\%Video LinuxLab 2018\fP, .IP \(bu 2 Evolution of (OTA) Update in the IoT world by Stefano Babic, ELC 2019, \fI\%Slides ELC 2019\fP, \fI\%Video ELC 2019\fP, .IP \(bu 2 There is No Store For Self\-Driving Car Parts by Stephen Segal and Matt Fornero (Cruise LLC), ELC 2020, \fI\%Slides Cruise ELC 2020\fP, \fI\%Video Cruise\fP .IP \(bu 2 Secure Boot and Over\-the\-Air Updates \- That\(aqs simple, no ? by Jan Kiszka (Siemens AG), ELC 2020, \fI\%Slides Secure OTA ELC 2020\fP, \fI\%Video Secure OTA\fP .UNINDENT .UNINDENT .UNINDENT .SS Useful references .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fI\%Boundary Devices, Using SWUpdate to upgrade your system\fP .IP \(bu 2 \fI\%Présentation de Software Update (French)\fP .IP \(bu 2 \fI\%Easy OS upgrades with SWUpdate\fP .IP \(bu 2 \fI\%SWUpdate for feature\-rich IoT applications\fP .IP \(bu 2 \fI\%Implement swupdate \- replacing opkg based updating, VictronEnergy\fP .IP \(bu 2 \fI\%Variscite, SWUpdate\fP .IP \(bu 2 \fI\%Updating Embedded Linux Devices: SWUpdate\fP .IP \(bu 2 \fI\%Approach to Software Update Management, Pelux\fP .IP \(bu 2 \fI\%SOTA System, Pelux\fP .IP \(bu 2 \fI\%Building a Linux system for the STM32MP1: remote firmware updates, Bootlin\fP .UNINDENT .UNINDENT .UNINDENT .SH CONTRIBUTING TO SWUPDATE .sp Contributions are welcome ! Please follow the following guideline for contributions. .SS Contribution Checklist .sp These are mostly general recommendations and are common practice in a lot of FOSS projects. .INDENT 0.0 .IP \(bu 2 use git to manage your changes [\fIrecomended\fP] .IP \(bu 2 follow as much as possible kernel codestyle [\fIrecomended\fP] Nevertheless, some rules are not so strict as in kernel. The maximum line length can be extended over 80 chars if this increase code readability. .IP \(bu 2 add the required copyright header to each new file introduced [\fBrequired\fP] .IP \(bu 2 .INDENT 2.0 .TP add signed\-off to all patches [\fBrequired\fP] .INDENT 7.0 .IP \(bu 2 to certify the "Developer\(aqs Certificate of Origin", see below .IP \(bu 2 check with your employer when not working on your own! .UNINDENT .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B add version number for your patches if follow\-up versions are requested [\fIrecomended\fP] .INDENT 7.0 .IP \(bu 2 Add a "Change from Vx" description under the commit message to take track of the history of the patch. .IP \(bu 2 It is suggested to use excellent "patman" tool to manage patches series. This is part of U\-Boot\(aqs project (tools/patman), but it can be used in other projects, too. .UNINDENT .UNINDENT .IP \(bu 2 check that your patches do not break build [\fBrequired\fP] .INDENT 2.0 .IP \(bu 2 There is a set of configuration files in the \fIconfigs/\fP directory. Please run a build for all files in the directory to ensure that SWUpdate is still buildable from configurations different as yours. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP post patches to mailing list [\fBrequired\fP] .INDENT 7.0 .IP \(bu 2 use \fIgit format\-patch\fP to generate your patches. .IP \(bu 2 use \fIgit send\-email\fP if possible. This avoid corruptions due to the mailers .IP \(bu 2 add a prefix [meta\-swupdate] if patches are intended to the Yocto\(aqs meta layer. .IP \(bu 2 send patches inline, do not append them .IP \(bu 2 no HTML emails! .UNINDENT .UNINDENT .IP \(bu 2 do not use github Pull Request. github facilities are not used for this project. The review is done in a single place : the Mailing List. PR from github are ignored. .UNINDENT .sp Patches are tracked by patchwork (see \fI\%http://jk.ozlabs.org/projects/patchwork/\fP). You can see the status of your patches at \fI\%http://patchwork.ozlabs.org/project/swupdate/list\fP\&. .SS Developer\(aqs Certificate of Origin 1.1 .sp When signing\-off a patch for this project like this .INDENT 0.0 .INDENT 3.5 Signed\-off\-by: Random J Developer <\fI\%random@developer.example.org\fP> .UNINDENT .UNINDENT .sp using your real name (no pseudonyms or anonymous contributions), you declare the following: .INDENT 0.0 .INDENT 3.5 By making a contribution to this project, I certify that: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP a. 3 The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or .IP b. 3 The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or .IP c. 3 The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it. .IP d. 3 I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign\-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SH PROJECT'S ROAD-MAP .sp Please take into account that most of the items here are \fIproposals\fP\&. I get some ideas talking with customers, some ideas are my own thoughts. There is no plan when these features will be implemented \- this depends if there will be contribution to the project in terms of patches or financial contributions to develop a feature. .sp Thanks again to all companies that have supported my work up now and to everybody who has contributed to the project, let me bring SWUpdate to the current status ! .SS Main goal .sp First goal is to reach a quite big audience, making SWUpdate suitable for a large number of products. This will help to build a community around the project itself. .SS Support for further compressors .sp SWUpdate supports image compressed with following formats: zlib, zstd. This is a compromise between compression rate and speed to decompress the single artifact. To reduce bandwidth or for big images, a stronger compressor could help. Adding a new compressor must be careful done because it changes the core of handling an image. .SS More efficient delta updates .sp A whole update could be very traffic intensive. Specially in case of low\-bandwidth connections, it could be interesting to introduce a way for delta binary updates. There was already several discussions on the Mailing List about this. If introducing binary delta is high desired, on the other side it is strictly required to not reduce the reliability of the update and the feature should not introduce leaks and make the system more vulnerable. It is accepted that different technologies could be added, each of them solves a specific use case for a delta update. .sp SWUpdate is already able to perform delta updates based on librsync library. This is currently a good compromise to reduce complexity. Anyway, this helps in case of small changes, and it is not a general solution between two generic releases. A general approach could be to integrate SWUpdate with a storage to allow one a delta upgrade from any release. .SS Parser .sp SWUpdate supports two parsers : libconfig and JSON. It would be nice if tools can be used to convert from one format to the other one. Currently, due to some specialties in libconfig, a manual conversion is still required. .SS Self contained tool to generate Update Packages (SWU) .sp Generation of SWUs is fully supported inside OE via meta\-swupdate, but there is no support at all with other buildsystems (Buildroot, Debian). The user have a not preordered bunch of programs and scripts to generate the SWU, and mostly they are not generic enough. It will be interesting to create a \fIbuildswu\fP tool, running on host system, that can create form a configuration a SWU. The tool must support all features, that means it should be able to pack artfact, generate sw\-description from templates, sign the SWU, encrypt the artifact, etc. .SS Software\-Software compatibility .sp SWUpdate has from the early stage a hardware to software compatibility check. In case software is split in several components (like OS and application), it is desirable to have a sort of software compatibility check. For example, SWUpdate verifies if a component (like an application) is compatible with a runningOS and reject the update in case of mismatch. .SS Handlers: .SS New Handlers .sp Users develop own custom handlers \- I just enforce and encourage everyone to send them and discuss how to integrate custom handler in mainline. .INDENT 0.0 .TP .B Some ideas for new handlers: .INDENT 7.0 .IP \(bu 2 FPGA updater for FPGA with Flash .IP \(bu 2 Package handler to install packages (ipk, deb) Packages can be inserted into the SWU and the atomicity is guaranteed by SWUpdate. .IP \(bu 2 Lua handlers should be added if possible to the project to show how to solve custom install. .UNINDENT .UNINDENT .SS Handlers installable as plugin at runtime .sp The project supports Lua as script language for pre\- and postinstall script. It will be easy to add a way for installing a handler at run\-time written in Lua, allowing to expand SWUpdate to the cases not covered in the design phase of a product. .sp Of course, this issue is related to the security features: it must be ensured that only verified handlers can be added to the system to avoid that malware can get the control of the target. .sp Current release supports verified images. That means that a handler written in Lua could be now be part of the compound image, because a unauthenticated handler cannot run. .SS Security .INDENT 0.0 .IP \(bu 2 add support for asymmetryc encryption .IP \(bu 2 add support to encrypted sw\-description .UNINDENT .SS Support for evaluation boards .sp meta\-swupdate\-boards contains examples with evaluation boards. Currently, there are examples using Beaglebone Black, Raspberri PI 3 and Wandboard. The repo is a community driven project: patches welcome. .SS Back\-end support (suricatta mode) .SS Back\-end: check before installing .sp In some cases (for example, where bandwidth is important), it is better to check if an update must be installed instead of installing and performs checks later. If SWUpdate provides a way to inform a checker if an update can be accepted before downloading, a download is only done when it is really necessary. .SS Back\-end: hawkBit Offline support .sp There are several discussions on hawkBit\(aqs ML about how to synchronize an offline update (done locally or via the internal Web\-server) with the hawkBit\(aqs server. Currently, hawkBit thinks to be the only one deploying software. hawkBit DDI API should be extended, and afterwards changes must be implemented in SWUpdate. .SS Back\-end: support for generic down\-loader .sp SWUpdate in down\-loader mode works as one\-shot: it simply try to download a SWU from a URL. For simple applications, it could be moved into \fIsuricatta\fP to detect if a new version is available before downloading and installing. .SS Back\-end: support for Mender .sp There was several discussion how to make a stronger collaboration between different update solution and a proposal discussed previously is to use SWUpdate as client to upgrade from a Mender server, see \fI\%BOF at ELCE 2017\fP .SS Support for multiple Servers simultaneously .sp Currently, suricatta\(aqs server backends are a mutually exclusive compile\-time choice. There is no interest to have multiple OTA at the same time. This feature won\(aqt be implemented and I will remove this from roadmap if no interest will be waked up. .SS Test and Continuous Integration .sp The number of configurations and features in SWUpdate is steadily increasing and it becomes urgent to find a way to test all incoming patch to fix regression issues. One step in this direction is the support for Travis build \- a set of configuration files is stored with the project and should help to find fast breakages in the build. More in this direction must be done to perform test on targets. A suitable test framework should be found. Scope is to have a "SWUpdate factory" where patches are fast integrated and tested on real hardware. .SS Documentation .sp Documentation is a central point in SWUpdate \- maintaining it up to date is a must in this project. .SH DOCUMENTATION FOR PREVIOUS RELEASES .INDENT 0.0 .IP \(bu 2 \fI\%2020.04\fP .IP \(bu 2 \fI\%2019.11\fP .IP \(bu 2 \fI\%2019.04\fP .IP \(bu 2 \fI\%2018.11\fP .UNINDENT .SH INDICES AND TABLES .INDENT 0.0 .IP \(bu 2 genindex .IP \(bu 2 modindex .IP \(bu 2 search .UNINDENT .SH AUTHOR Stefano Babic .SH COPYRIGHT 2013-2021, Stefano Babic .\" Generated by docutils manpage writer. .