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
The edition property identifies the version of assets for a particular structure.
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.
/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 filesystem-label:
namestructures are identified using/dev/disk/by-partlabelsymlinksfilesystem-labelstructures are identified using/dev/disk/by-labelsymlinks
Both name and 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.
Filesystem structures
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
some-assets/to `dir/
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.
Use of preserve to retain specific files inside non-filesystem structures is unsupported.
Caveats
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
- using
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