Ubuntu Core: how a device boots and recovers
overview for everyone for Ubuntu Core developers for administrators
An Ubuntu Core device has four partitions and boots in one of a few modes. This deck follows one device from installation through refreshes that can roll back to recovery and factory reset and points to the deck for each step.
On the map: ubuntu core boot
01 A device nobody visits
On Ubuntu Core the kernel, gadget, base, snapd and apps are all snaps. The boot design gives three properties: updates that roll back, a recovery system kept on disk, and optional encryption tied to the device.
Picture a small gateway bolted inside a cabinet at a customer's site. Nobody's going to walk up to it with a keyboard for years, so if an update goes wrong, nobody's coming. That's why everything on it is a snap that snapd-controls: the kernel, the gadget with the boot assets and device set-up, the base, snapd itself, and the apps. Three promises follow. A failed kernel or base update rolls back by itself. A spare system stays on the disk to repair or rebuild the device. And with encryption, the data opens only on this device. The rest of this deck shows where each promise comes from.
02 Four partitions, four jobs
ubuntu-seed: recovery bootloader and recovery systems. ubuntu-boot: run bootloader and kernels. ubuntu-save: device identity, kept across a factory reset. ubuntu-data: everything else. Only save and data are encrypted.
Open the gateway's disk and you find four partitions. Each one exists because of what has to survive what. ubuntu-seed holds the first bootloader and the recovery systems, each a complete set of snaps plus the device's model. ubuntu-boot holds the second bootloader and the kernels. ubuntu-save keeps what must outlive a factory-reset, like the device's identity. ubuntu-data holds everything else. With encryption on, only save and data are encrypted, because the device has to read seed and boot before it unlocks anything. And seed isn't read-only: snapd writes there now and then, to set the next boot mode or add a recovery system.
03 One device, several modes
run: the normal system. recover: a temporary system in memory; data untouched. factory-reset: boot and data rebuilt, ubuntu-save kept. install: everything rebuilt, ubuntu-save erased. snap reboot or the chooser picks the mode. The 1-key menu is console-conf's chooser, so it needs console-conf on the device and a keyboard attached.
Most days the gateway starts in run mode and you don't think about it. The other modes are for the bad days. Recover starts a temporary system in memory, from a recovery system, and leaves your data alone, so you can look at what went wrong. factory-reset rebuilds boot and data but keeps save, so the device keeps its identity. Install builds everything again and erases save too. You pick a mode with snap reboot, or, if someone's standing there with a keyboard, by holding the 1 key while it starts. There's a fifth mode as well, but it's only for confidential virtual machines in a cloud.
04 From power-on to snapd
Firmware, recovery bootloader on ubuntu-seed, run bootloader on ubuntu-boot, the kernel with snap-bootstrap in its initramfs, then snapd. In any mode other than run the first bootloader starts a recovery system's kernel from ubuntu-seed.
Press the power button and the gateway runs a relay. Five runners, and the mode travels along with them. The firmware starts the recovery bootloader on ubuntu-seed, which reads the mode. For run mode it hands over to the run bootloader on ubuntu-boot, and that one picks the kernel. Inside the kernel's initramfs, snap-bootstrap unlocks the encrypted partitions, mounts everything and picks the base. Then the real system starts, and snapd confirms that the boot worked. In any other mode the first bootloader skips ubuntu-boot and starts a recovery system's kernel from seed instead.
05 The life of a device
Image, install, first boot, run with refreshes that are tried and kept or rolled back, recover or factory reset when needed, and remodel to change what the device is.
Let's follow the gateway from the factory to the day it's retired. An image is a model and a set of snaps, written to ubuntu-seed. The first start is install mode: it makes the other partitions and, with encryption, seals the keys. First boot then seeds the snaps. After that the gateway lives in run mode, where each kernel or base refresh is tried once and kept only if that boot succeeds. On a bad day, recover lets you look around, and factory-reset starts over while keeping the identity. And a remodel moves the device to a new model without reinstalling it.
06 Three questions you can ask the device for users for administrators
snap model shows the device's model, snap recovery lists recovery systems, and snap reboot --recover restarts into recover mode, on the default recovery system unless a label is given. The next restart returns to run mode.
You don't need to open the cabinet to learn what the gateway is. Three commands tell you most of it. Snap model prints the brand, the model, and the serial that names this one device. Snap recovery lists the recovery systems on ubuntu-seed, by label. Current marks the one it was last seeded from, here the one it was installed from. The newer one, which you made the default, is marked default recovery. Then sudo snap reboot --recover, restarts into recover mode at once, using the default system unless you name another. Recover mode lasts one boot, so the next restart brings you back to run mode.
07 Data that opens only on this device
ubuntu-data and ubuntu-save can be encrypted. The key is unsealed only when the measured boot chain and model match; ubuntu-save's key is stored inside ubuntu-data. The full disk encryption district explains sealing, unlocking and recovery keys.
Suppose someone pulls the disk out of the gateway. What stops them from just reading it? If the hardware can do it and the model doesn't say otherwise, save and data are encrypted. The key for data is sealed so the TPM releases it only if the bootloaders, the kernel, the command line and the model measured during this boot match what snapd expected. Data opens first, and it holds the key for save. If something in that chain was changed behind snapd's back, the key stays sealed, and the recovery key is the way in. When snapd changes one of those pieces itself, it reseals first.
08 Where to go from here
Four districts: boot, bootloaders, install and recovery, full disk encryption. Each starts with an overview deck and follows the life of a device.
That's the whole of Ubuntu Core from the outside. Now pick a door. For the boot itself, start with the walk from power-on to snapd, then the other modes, try and rollback, reboots and the kernel command line. The bootloader district starts with what snapd asks of any bootloader, then has a deck each for GRUB, the Raspberry Pi, U-Boot and Little Kernel. Install and recovery starts with the model and follows the device's life: the seed, install, recovery systems, factory-reset and remodel. Encryption starts with what's encrypted and who decides.
Read more
The four partitions
| Partition | Holds | Encrypted |
|---|---|---|
| ubuntu-seed | recovery bootloader, its boot variables, recovery systems, and the snap files they share | no |
| ubuntu-boot | run bootloader, its boot variables, unpacked kernels, the sealed run key | no |
| ubuntu-save | device key and serial backup, per-snap save data, encryption state | when encryption is on |
| ubuntu-data | snaps, snapd state, system and user data, the key for ubuntu-save | when encryption is on |
An encrypted partition carries the label with -enc appended, for example ubuntu-data-enc. ubuntu-seed is mounted writable in run mode: snapd writes the next boot mode and new recovery systems there.
The modes
| Mode | Started from | Root file system | What is erased |
|---|---|---|---|
run | ubuntu-boot kernel | ubuntu-data | nothing |
install | a recovery system | temporary, in memory (or installed and run in one boot) | boot, data and save |
recover | a recovery system | temporary, in memory | nothing |
factory-reset | a recovery system | temporary, in memory | boot and data; save and seed are kept |
cloudimg-rootfs | Azure confidential VM image | the image's data partition | nothing |
Recover mode lasts one boot: the next restart returns to run mode.
for Ubuntu Core developers for administrators for snapd developers
Where things are
| Partition | Gadget role | On disk |
|---|---|---|
| ubuntu-seed | system-seed | recovery systems under systems/<label>/, the shared snaps/ pool, the recovery bootloader's variables |
| ubuntu-boot | system-boot | the run bootloader's variables, unpacked kernels, the sealed run key |
| ubuntu-save | system-save | device key and serial backup, per-snap save data |
| ubuntu-data | system-data | snaps, snapd state, the key for ubuntu-save |
The mode is the kernel argument snapd_recovery_mode; the recovery system is snapd_recovery_system. A present but empty mode means install. The modeenv is the file through which snapd and the initramfs agree on the mode, the base, the trusted kernels, the trusted boot assets and the kernel command lines.
Words used across the area
- Recovery system: a set of snaps with a model assertion and snap assertions on ubuntu-seed, named by a label such as
20260301, from which the device can be installed, recovered or reset. - Try boot: one boot with a new kernel or base. snapd keeps it only after that boot succeeds.
- snap-bootstrap: the program in the initramfs that finds the disk, unlocks and mounts the partitions and selects the snaps to boot.
- Boot variables (bootenv): the few variables snapd stores where the bootloader can read them.
Commands
| Command | What it shows or does |
|---|---|
snap model | the device's brand, model and serial, and its grade and storage safety when the model sets them |
snap recovery | recovery systems: Label, Brand, Model, Notes (current, default-recovery) |
snap reboot | a plain reboot |
snap reboot --recover [label] | reboot into recover mode |
snap reboot --factory-reset [label] | reboot into factory-reset mode |
snap reboot --install [label] | reboot into install mode; erases the device |
snap reboot --run | reboot into run mode (current system only) |
In snap recovery, current marks the system the device was last seeded from: the one it was installed or factory reset from, or remodelled to. default-recovery marks the system chosen as the default, for example when it was created with "mark default". Without a label, --recover, --factory-reset and --install use the default recovery system, or the current one if no default is set.
At the device itself, holding the 1 key on a keyboard for two seconds, while the trigger service waits for it at start-up (up to ten seconds), opens a menu of recovery systems and modes. The menu is console-conf's recovery chooser: it runs in the booted system, needs an input device, and needs console-conf on the device.
Further reading
- Inside Ubuntu Core: the partitions and the boot process in brief, with diagrams of the disk before and after installation.
- Storage layout: one section per partition.
- Recovery modes: what each mode means for the owner of the device.
- Snaps in Ubuntu Core: the snap types the system is built from.
- Ubuntu Core 26: release notes, including installation from the initramfs.
Roads from here
START HERE
- snapd — back to the overview
UBUNTU CORE · boot
- From power-on to snapd — every step from power-on to snapd in run mode
- Run, install, recover, factory reset — what install recover and factory reset do differently
- Try, trying, done — how a new kernel or base is tried and rolled back
- Reboots and snap reboot — why a refresh reboots and what snap reboot does
- The kernel command line — who may change the kernel command line
UBUNTU CORE · bootloaders
- Bootloaders: one interface, six implementations — what snapd asks of any bootloader
- GRUB on Ubuntu Core — GRUB on x86 and arm64 UEFI devices
- Raspberry Pi: piboot and tryboot — the Raspberry Pi firmware and tryboot
- U-Boot — U-Boot boards
- Little Kernel and Android boot — Little Kernel and Android boot
UBUNTU CORE · install and recovery
- Model, gadget and kernel — the model assertion and the gadget and kernel snaps
- ubuntu-seed and first boot — what is on ubuntu-seed and how first boot uses it
- Install mode — what install mode does to the disk
- Recovery systems — listing creating and testing recovery systems
- Factory reset, ubuntu-save and remodel — factory reset and ubuntu-save and remodeling
UBUNTU CORE · full disk encryption
- What is encrypted and who decides — what is encrypted and who decides
- Sealed keys, boot chains and resealing — sealed keys and boot chains and resealing
- Unlocking at boot — how the disk is unlocked at boot
- Encryption without a TPM — encryption without a TPM
- Recovery keys, passphrases, DBX and repair — recovery keys and passphrases and repair