Firmware update¶

An installed machine is updated without a USB stick. The update package is installed beside the running version rather than over it: settings, data and passwords survive the update, and the previous version stays on the boot partition for a rollback.

The machine downloads and installs nothing on its own. Installing an update is always an explicit request: from the interface, from the API, or by hand at the console.

The update package¶

The package is an archive of what goes onto the boot partition: the boot file of the new version, its layer images, the loader menu entry, the product description and a manifest of checksums. The package's own checksum is published next to it.

The update channel¶

The machine learns about new versions from the index of an update channel whose address is compiled into the build. It reads the index and lists the versions of its own product and its own architecture; the ones already on the partition are marked.

A build without a channel does not know about one at all, and can only be updated by URL or by file.

Installing¶

From the web interface¶

The Updates section opens with two versions: the one running and the one that will boot next. Next to them is the reboot button — when the next version differs from the running one it is highlighted, and the screen says what exactly will change on reboot.

The channel index is read when the interface is opened: the menu item carries a mark when the channel holds a version that is not on the partition. The Check for updates button re-reads the index.

Through the API¶

The response comes back at once and the installation runs in the background.

Install a package from a file:

curl -u admin:password -H 'content-type: application/x-tar' \
    --data-binary @mcaster-<version>-amd64.update.tar http://<machine>:8090/system/firmware

Install a package from a URL:

curl -u admin:password -H 'content-type: application/json' \
    -d '{"url":"https://…/mcaster-<version>-amd64.update.tar"}' \
    http://<machine>:8090/system/firmware/install

See the progress of the operation, the installed versions and the one that boots next:

curl -u admin:password http://<machine>:8090/system/firmware

List the versions in the update channel:

curl -u admin:password http://<machine>:8090/system/firmware/available

Reboot into the new version:

curl -u admin:password -X POST http://<machine>:8090/system/reboot

What happens during an installation¶

1. The daemon unpacks the package onto the mutable data partition.
2. It verifies every file against the manifest of checksums, and the product, the architecture and the hardware profile against the running ones.
3. Only then it remounts the boot partition for writing and copies what is missing. Layer images shared with the versions already installed are not copied.
4. It points the loader's default entry at the new version.

After the installation the partition holds the running version and the new one. The rest are removed together with the layer images nobody needs any more.

The new version starts working only after a reboot — the installation does not reboot the machine by itself.

Rollback¶

A rollback is picking the previous version and rebooting:

curl -u admin:password -X POST http://<machine>:8090/system/firmware/<version>/select
curl -u admin:password -X POST http://<machine>:8090/system/reboot

Remove a version that is no longer needed:

curl -u admin:password -X DELETE http://<machine>:8090/system/firmware/<version>

The running version and the selected one cannot be removed.

When the daemon is not there¶

If the daemon has not come up or cannot be reached, the same path is walked by hand at the console as root. The firmware-update program lives in the base layer, depends only on the shell and the layer's utilities, and does exactly three things — download, put in place, switch — with the same checks the daemon makes. It removes nothing.

firmware-update install https://…/mcaster-<version>-amd64.update.tar   # or a path to a file
firmware-update list                     # versions on the partition: running and next
firmware-update select <version>         # boot the previous version next time
systemctl reboot