Updating gadget boot assets
A gadget snap’s boot assets can be automatically updated when the snap is refreshed. It’s the responsibility of the gadget snap publisher to ensure the correctness and consistency of the update data, as outlined below.
- the update process relies heavily on the information provided in gadget.yaml as it attempts to verify the internal consistency of the gadget description
- gadget and kernel snap versions are not coupled. This means updated boot assets must be able to boot the old and new kernels of a given gadget
- a device will reboot after boot assets have been updated
snapd 2.42+ is required for automatic boot assets updates and snapd 2.43+ employs early consistency checks when building gadget snaps.
Enabling boot asset updates
Automatic boot asset updates are enabled by adding an
update section below the
structure: definition in a gadget snap’s gadget.yaml:
volumes: my-volume: structure: - name: some-structure .. update: edition: 2
edition property identifies the version of assets for a particular
Updates are performed when the
edition value is higher than the value in the currently installed gadget snap. If this is the case, snapd next attempts to analyse the currently written assets so that only those that differ are updated.
Backup and rollback
When an update is performed, snapd first creates a backup of all modified boot assets for both filesystem and non-filesystem structures. Backups are kept on the
writable partition inside the snapd state directory and are cleaned-up after an update has been applied.
A rollback is only performed when the process of writing updated boot assets fails. Once the assets have been written, the changes will not be undone, even if a later step of snap installation fails.
Volume and structures
Snapd analyses the
volumes declaration in
gadget.yaml to map its members against partitions on the main block device used by the system.
The main block device is the one with
/writablepartition on it.
A volume layout is built with the following constraints:
- 512 byte sector size
- 1MB default starting offset for the first non-MBR partition, unless otherwise specified
The volume layout describes the exact position of each structure (partition) and their content. At runtime, structures are identified by either their defined
name or a
namestructures are identified using
filesystem-labelstructures are identified using
filesystem-label must be unique amongst all named structures and labelled filesystems.
Volume structures obviously need to be named, and the filesystem needs to be labelled, to allow snapd to easily identify corresponding partitions and mount locations.
Structures containing filesystems can be updated if the filesystem is mounted at runtime and is accessible to snapd. The update process then writes the files and directories listed in the
content section of the structure.
Specific entries can be retained during the update by listing each individual item in the
preserve list of the
update structure, as shown below:
volumes: my-volume: structure: - name: some-fs-structure type: <uuid> filesystem: ext4 size: 10M content: - source: a.data target: / - source: some-assets/ target: dir/ update: edition: 2 preserve: - a.data - b.env - dir/keep
In the above example, the boot assets update process will:
- deploy the
a.datafile into the root (
- copy the contents of
Should any of the entries listed in the
preserve section exist beforehand, they will be preserved intact.
Unnamed and non-filesystem structures
Support for unnamed non-filesystem structures, or structures without a partition table entry,
type: bare or
filesystem: none, for example, are enabled via a fallback mechanism:
snapd identifies the partition carrying the
writable filesystem and proceeds to apply the updates to the parent device. For example, assuming
/writable is mounted from
/dev/mmcblk0p2, the fallback mechanism would identify
/dev/mmcblk0 as the parent device.
The contents of these structures can also be updated in the boot assets update process. Each image listed in the
content section is written to the structure, as shown below:
volumes: my-volume: structure: - name: some-structure type: <uuid> filesystem: none size: 1M content: - image: raw.img - image: other.img offset: 10240 update: edition: 2
With the above example, the boot assets update process will write the contents of
raw.img at the 0 offset inside the partition corresponding to the structure, while
other.img is written at 10kB offset from the start of the partition.
preserve to retain specific files inside non-filesystem structures is unsupported.
Currently, boot asset updates have the following limitations:
- the gadget snap can have only one defined volume
- the updated gadget snap must use the same structure-level layout
- once all of changed boot assets have been updated, the original files and images will not be restored from the backup, even if a later step of the installation fails
- a device will still reboot when an update is applied, even when no boot assets are effectively changed
- there must be enough space on the
writablepartition to hold a backup copy of all modified boot assets
The following are also unsupported:
- encrypted or otherwise nested structures, such as LVM volumes
preserveinside non-filesystem structures
- updating unnamed and unlabelled filesystem structures
- updating devices not described inside
gadget.yaml, such as the BOOT1/2 regions of SD cards
Last updated 1 year, 10 months ago.