Storage layout

Ubuntu Core docs
1

Storage layouts for Ubuntu Core have been designed to support recovery modes, and the following partitions are used:

  • ubuntu-seed: configuration for the first-stage/recovery boot loader
  • ubuntu-boot: second-stage/run bootloader and unpacked kernel(s)
  • ubuntu-save: cross-installation device identity and selected snap backup data
  • ubuntu-data: user and system data and is expanded upon installation

See below for more details on each partition. Additional partitions may be required by the device/board specific bootloader.

On UEFI systems, ubuntu-seed is intended to be the EFI System Partition (ESP) with its specific GUID and must be vfat formatted.

Whether ubuntu-seed or ubuntu-boot are vfat or ext4 formatted depends on the capabilities and requirement of the specific bootloader. Some bootloaders might support ext4 but not robustly. With grub on UEFI systems, for example, ubuntu-seed will be vfat-formatted while ubuntu-boot can be ext4-formatted.

The definitive layout of the generated image used to install Ubuntu Core, and the resultant storage on the device, is described by the gadget snap and its associated gadget.yaml file.

A device image for both Ubuntu Core 20 and Ubuntu Core 22 devices must only contain bootloader-specific partitions and ubuntu-seed, such that a recovery system in it can be booted into install mode. Installation will create and size the other missing partitions.

See Installation process for more details on how an installation proceeds.

ubuntu-seed

role: system-seed; read-only, ext4 or typically vfat

This partition contains the configuration for the first-stage/recovery boot loader and at least one recovery system. This is a set of snaps (base, kernel, gadget and application snaps, see Snaps in Ubuntu Core for more details), together with a model assertion and snap assertions that define the device and for which the device can be recovered or reinstalled .

ubuntu-seed layout

When the image is created, the recovery systems partition is populated with any required bootloader-specific binaries and assets extracted from the gadget.

In all cases, ubuntu-seed will contain the following directories:

  • One or more systems/<system-label> recovery system directories

    The <system-label> for these directories is usually date-based, e.g. 20201210, and each fully describes a recovery system, comprising:

    • a model file containing the model assertion for the recovery system
    • an assertions directory that includes all the other assertions needed by the system
    • a kernel image, or other bootloader-specific information to help find the appropriate kernel

    The model and all the assertions together determine which snaps and revisions compose the system and they can be used to verify and cross-reference them.

  • A snaps directory which operates as a pool of snaps shared across all recovery systems. The assertions in a recovery system will define and reference which of these will be used by the system.

ubuntu-boot

role: system-boot; read-only, ext4 or vfat

Contains the second-stage/run bootloader and unpacked kernel(s) to boot and with.

ubuntu-save

role: system-save; writable, ext4

Stores device identity backup data and data to facilitate recovery or re-install.

This partition is mandatory on encrypted systems where it should have a minimum size of approximately 20+MB to handle volume and file system creation.

From snapd 2.57+, snaps can save small amounts of persistent data to the ubuntu-save partition. This location is accessible from the SNAP_SAVE_DATA environment variable.

This data might include certificates, data blobs, or configuration files, to help snaps function. This data will survive a factory reset, and consequently, the stored data should be device-oriented and not specific to a particular user of the device.

Device provisioning needs to consider space requirements and snap developers need to understand the consequences of storing persistent data to ubuntu-save.

ubuntu-data

role: system-data; writable, ext4

This partition stores user and system data. This partition is often minimally sized in the image but extended during device initialisation to use all the space available.

1 Like
2

It would be useful to detail which partition is preserved and which partition is deleted during each recovery type. A partition / recovery table would be nice.
Is ubuntu-save preserved during a factory reset?

3

@degville With snapd 2.57 the usage ubuntu-save partition has been extended to allow snaps to store small but persistant data. The data will survive factory reset and could be things like certificates, data blobs or configuration files that are needed by the snap to function. It is now important that provisioners of ubuntu-core have in mind that ubuntu-save partition should be large enough if they use or develop snaps that require data to reside there. And snap developers that use this feature should be mindful about what they put there.

4

Thanks for the update Philip! That’s really good information. I’ve updated the ubuntu-save definition to include this. It’s a little on the large side now, so I will try to improve the structure of this page and move partition details from the current bullet list.

1 Like
5

@degville

From snapd 2.57+, snaps can save small amounts of persistent data to the ubuntu-save partition.

This maybe should point to the SNAP_SAVE_DATA documentation for snaps.

This data will survive a factory reset. Device provisioning needs to consider space requirements and snap developers need to understand the consequences of storing persistent data to ubuntu-save …

This maybe should b expanded:

As it survives factory-reset it is recommended for storing device-oriented data and not data belonging to a particular user of the device.

6

Thanks for the suggestions, @pedronis. I’ve restructured the doc to help us expand this documentation if needed, and incorporated your updates.