Setting up online updates for Neutrino

As far as I am aware, almost from the beginning of the distribution of dBox images, it was possible to update images online. Already the AlexW-images had this property. This requires one setup file in the image, pointing to the server, and one, "table-of-content"-like file on the server, pointing to the files the client are offered to download and install.

The last few years, this possibility has not been abandoned, but has "faded". Originally, "update image" meant the root partition, using the cramfs filesystem, that was replaced, while leaving the /var-partition, containing the user settings and preferences, intact. Today, many (but not everyone!) prefers full images, which the Neutrino online update mechanism, for no obvious reason, does not support.

Some years ago, images where the root partition used the so-called squashfs-filesystem emerged. The update mechanism of Neutrino was updated to reflect this, however, the programmer(s) implementing the change seemed to strive for making the world a better place for squashfs-users, while the rest of the world population should blame themselves for being stupid. The file update.cpp relied on the C Preprocessor symbol SQUASHFS conditionally compiling in either the code for flashing squashfs partitions, or, cramfs-partitions. Thus, a high-level GUI-program was (intended to be) differently compiled dependent on the underlying file system!

A patch to Neutrino fixing these shortcomings was checked in in 2006-03-19, with a subsequent fix the day after (thanx JtG-riker!). The rest of this article applies only to CVS after that date.

The /etc/cramfs.urls configuration file

The only setup file for the update mechanism residing on the dBox was traditionally called /etc/cramfs.urls, and contained one or many lines pointing to URLs containing "table-of-content"-files, listing image files offered for download. (Configurable through dBox -> Service -> Software Update -> Expert Functions -> config file.) Although the name is an anachronism, it is suggested to stay with it.

The "Table-of-Content"-file, *.list

The "Table-of-Content"-file, traditionally with a .list suffix, lists the images the server makes available in machine readable format. Each line describes a downloadable image, and has four or more white-space separated fields: The first contains the URL of the downloadable image, the second the MD5-checksum, the third the version string in the Tuxbox SBBBYYYYMMTTHHMM convention (see, e.g. mkversion). The subsequent fields (at least one must be present) consists of a informal verbal description for the user. (Due to restrictions in present Neutrino updating, only very short strings are suitable.)

Creating the setup files with newmake

newmake supports automatically creating the /etc/cramfs.urls and some .list-files. To enable, use the option --with-updatehttpprefix=URL, where the argument should be the URL of the .list-files, with the last component removed. Thus, an /etc/cramfs.urls-file will be generated, containing URLs to .list-files. See cdk/make/cramfs.urls.mk. This make target is customizable with the usual newmake customization mechanism. There are also make targets cramfs.list, squashfs.list, img.list, and allimages.list, see cdk/make/distribution-lists.mk, that will create some suitable list-files. Using the customization facility of these targets to copy the list-files and the corresponding images to a distribution server might be a good idea.

The above mentioned patch changes Neutrino's behavior in the following way: First, the MD5-checksum of the downloaded image is computed, and compared to the MD5-sum in the list-file. If they are different, the image is rejected. (Previously, this test was made only with squashfs-images.) If the file name (or, more correctly, the last component of the URL) contains the string ".cramfs", the images is required to be a correct cramfs-image, and rejected if a test fails. Then the image size is compared to the size of the "Flash without bootloader"-partition. If equal, it is attempted to flash the image as a full image. The corresponding partition is the partition with the description "Flash without bootloader", it is not assumed to be partition /dev/mtd/4. If not, if the size is less or equal to the root partition, the images will be flashed into the root partition (always assumed to be /dev/mtd/2, since this presently holds true for all images built from CVS). Otherwise the image is rejected.

One beauty spot is that the Neutrino GUI presents the same error message (LOCALE_FLASHUPDATE_MD5SUMERROR) for different reasons. However, on the console, more detailed error information is presented.