GRUB on Ubuntu Core
one bootloader for Ubuntu Core developers
On UEFI devices the gadget ships signed shim and GRUB binaries and snapd ships both GRUB configuration files. A GRUB on ubuntu-seed chooses the mode and a GRUB on ubuntu-boot chooses the kernel through two symlinks. State is kept in three grubenv files and snapd replaces its own grub.cfg when a newer edition is built in.
On the map: ubuntu core bootloaders
01 The gadget brings the binaries, snapd brings the script
The gadget ships signed shim and GRUB binaries and an empty marker grub.conf. snapd writes EFI/ubuntu/grub.cfg on both partitions from its built-in grub-recovery.cfg and grub.cfg.
Open the gateway's gadget snap and look for the GRUB configuration. You won't find one. There's an empty file called grub.conf, and all it says is: this device uses GRUB. Next to it sit the signed shim and GRUB binaries, built from Ubuntu's packages. The scripts come from snapd. It has two built in, one for each stage, and writes them as grub.cfg onto the seed and boot partitions. That's why the logic of modes and kernel tries can change with a snapd refresh, not a gadget refresh. On Ubuntu Core sixteen and eighteen it was the other way round: the gadget shipped the script.
02 What sits on each partition
ubuntu-seed holds shim, the first GRUB, EFI/ubuntu/grub.cfg, grubenv and a grubenv per recovery system. ubuntu-boot holds a second GRUB, its config and environment, and one extracted kernel.efi per kernel snap.
Let's mount the gateway's two unencrypted partitions and look. The seed partition is the EFI system partition. It has shim in the firmware's default place, and again under EFI/ubuntu, next to the first GRUB, its script and its grubenv. Each recovery system gets a small grubenv of its own. The boot partition has a second GRUB, its own script and environment, and a folder per kernel snap holding one file, kernel.efi, with a symlink to the current one. What shim checks and measures is outside snapd. snapd knows these files by name, hashes them, and points the firmware's boot entry at shim.
03 Three small files hold the state
Three grubenv files: on ubuntu-seed for the mode and recovery system, in each systems/<label> for that system's kernel and command line, and on ubuntu-boot for kernel_status and the command line. Each is exactly 1024 bytes with no checksum; snapd truncates and rewrites it in place.
GRUB can read files and save a few variables. On the gateway, everything it remembers between boots lives in three files, each exactly a kilobyte. The one on seed answers two questions: which mode, and which recovery system. snapd keeps a few extras there too. Each recovery system has its own, naming that system's kernel snap and command line. The one on-boot holds the kernel_status and the run command line. The format is GRUB's: a header, key=value lines, and hash characters as padding. There's no checksum and no second copy, and snapd overwrites the file in place, so it doesn't move on disk.
04 A kernel refresh, seen as files
snapd extracts kernel.efi into EFI/ubuntu/<snap-file>/ on ubuntu-boot. kernel.efi and try-kernel.efi are relative symlinks into those folders, replaced atomically.
Here's the gateway's kernel refresh again. Watch one folder on the boot partition. The run GRUB starts before anything has unlocked the data partition, so the kernel can't come from there. Instead, snapd extracts one file, kernel.efi, into a folder named after the new snap file. The try is a second symlink, try-kernel.efi, plus the kernel_status set to try. After a good boot, snapd points the first symlink at the new kernel and removes the second. Both links are relative and swapped atomically, and snapd refuses a try link to a kernel it hasn't extracted. The try deck explains why that order is safe.
05 The fallback entry reboots
With kernel_status=try GRUB saves trying and sets fallback=1. The fallback entry prints "Cannot start new kernel - booting previous one" and reboots, because the TPM measurements of the failed attempt would prevent unsealing the key.
Suppose the new kernel is so broken GRUB can't even start it. The old kernel's right there in the next folder. Why not just load that? When the status is try, the script saves trying and sets GRUB's fallback to the second menu entry, and only then chainloads the try kernel. If that fails, the second entry runs. It prints a message and reboots. The script's comment says why: the TPM measurements have to be cleaned up before the key can be unsealed. A reboot starts them afresh. GRUB finds trying, clears it and boots the old kernel. So a kernel that won't even load costs one extra reboot.
06 The edition header
A managed grub.cfg starts with # Snapd-Boot-Config-Edition: N. A snapd refresh replaces the run config only when its built-in edition is higher, then reboots. The recovery config on ubuntu-seed is not updated at runtime.
snapd wrote the gateway's GRUB script at install time, and snapd has been refreshed many times since. Is the script still the factory one? Each built-in script starts with a comment carrying an edition number. After every snapd refresh, a task compares the edition on disk with its own. On the gateway both say three, so nothing happens. On an older device with edition two, the file's replaced and the device reboots. A new edition can change the static command line, so snapd records that first and reseals. A file without the header is left alone. And only the run script is updated; the recovery side isn't supported yet.
08 Where to go from here
Roads: the bootloader interface, the boot path, try and rollback, the command line, boot chains, recovery systems and the overview.
GRUB is the bootloader snapd knows best, and the only one it writes the script for. Here's where its neighbours are. The bootloaders deck has the interface GRUB implements more of than any other. The boot path walks a whole run-mode boot through both GRUB stages. Try and rollback explains what try and trying mean. The command line deck shows how those variables get filled. Sealing explains why the hashes of shim and GRUB matter. Recovery systems covers the systems this menu lists. And the Ubuntu Core overview is one step back.
Read more
Files
| Partition | Path | What it is |
|---|---|---|
| ubuntu-seed | EFI/boot/bootx64.efi | shim, in the firmware's default location |
| ubuntu-seed | EFI/boot/fbx64.efi | shim's fallback program; not part of a trusted chain |
| ubuntu-seed | EFI/ubuntu/shimx64.efi | shim |
| ubuntu-seed | EFI/ubuntu/grubx64.efi | the first GRUB |
| ubuntu-seed | EFI/ubuntu/grub.cfg | snapd's grub-recovery.cfg |
| ubuntu-seed | EFI/ubuntu/grubenv | mode and recovery system |
| ubuntu-seed | systems/<label>/grubenv | that system's kernel and command line |
| ubuntu-boot | EFI/boot/grubx64.efi | the second GRUB |
| ubuntu-boot | EFI/ubuntu/grub.cfg | snapd's grub.cfg |
| ubuntu-boot | EFI/ubuntu/grubenv | kernel status and command line |
| ubuntu-boot | EFI/ubuntu/<snap-file>/kernel.efi | an extracted kernel |
| ubuntu-boot | EFI/ubuntu/kernel.efi, try-kernel.efi | symlinks to the current and the try kernel |
On a running device EFI/ubuntu of ubuntu-boot is also visible as /boot/grub, and ubuntu-seed as /boot/efi. arm64 uses grubaa64.efi. Architectures other than amd64 and arm64 have no GRUB assets in snapd.
The three grubenv files
| File | Variables | Read by |
|---|---|---|
ubuntu-seed EFI/ubuntu/grubenv | snapd_recovery_mode, snapd_recovery_system, try_recovery_system, recovery_system_status, snapd_good_recovery_systems, snapd_boot_flags | the seed GRUB loads the first two; the rest are for snapd |
ubuntu-seed systems/<label>/grubenv | snapd_recovery_kernel, snapd_extra_cmdline_args, snapd_full_cmdline_args | the seed GRUB |
ubuntu-boot EFI/ubuntu/grubenv | kernel_status, snapd_extra_cmdline_args, snapd_full_cmdline_args | the run GRUB |
Format: exactly 1024 bytes; first line # GRUB Environment Block; key=value lines; padded with #. A file of another size is rejected: "grubenv %q must be exactly 1024 byte, got %d".
snapd_recovery_kernel is the kernel snap's path inside ubuntu-seed, for example /snaps/pc-kernel_2901.snap. An unasserted kernel on a dangerous model is under /systems/<label>/snaps/. After an install from recovery system 20260301 the seed environment holds snapd_recovery_mode=run and snapd_recovery_system=20260301.
What the run grub.cfg does with kernel_status
| Value at boot | Action |
|---|---|
try | save trying, set fallback=1, boot try-kernel.efi |
trying | clear it, boot kernel.efi |
| any other non-empty value | print "invalid kernel_status!!!", clear it, boot kernel.efi |
| empty | boot kernel.efi |
Editions and static command lines
| Config | Edition | Static arguments on x86-64 | On arm64 |
|---|---|---|---|
grub.cfg (run) | 3 | console=ttyS0,115200n8 console=tty1 panic=-1 | panic=-1 |
grub.cfg (run), editions 1 and 2 | 1, 2 | console=ttyS0 console=tty1 panic=-1 | panic=-1 |
grub-recovery.cfg | 2 | console=ttyS0 console=tty1 panic=-1 | panic=-1 |
A grub.cfg without the edition header is not updated, and is treated as edition 1 when the command line is computed. The task update-managed-boot-config is added to every refresh of the snapd snap on Ubuntu Core; it replaces the run grub.cfg only when the built-in edition is higher, and requests a system restart when it changed the file or the command line.
Menu entries of the seed GRUB
| Entry | Hotkey | What it does |
|---|---|---|
| Continue to run mode | n | chainloads the GRUB on ubuntu-boot |
Recover using <label> | r | saves snapd_recovery_mode=run, then boots the system's kernel in recover mode |
Install using <label> | i | boots the system's kernel in install mode |
Factory reset using <label> | i | boots the system's kernel in factory-reset mode |
| UEFI Firmware Settings | f | enters the firmware set-up |
Install and Factory reset are both given the hotkey i in the configuration. With no mode stored, the default mode is install; with no system stored, the lowest label is used. "Continue to run mode" is only offered when a partition labelled ubuntu-boot is found. Hybrid classic systems use grub-recovery-hybrid.cfg, which offers one entry for the mode and system snapd selected, and defaults to run mode when that system is missing.
Trusted assets and shim updates
- Recovery chains accepted:
EFI/ubuntu/shimx64.efithenEFI/ubuntu/grubx64.efi, orEFI/boot/bootx64.efithenEFI/boot/grubx64.efi. - The run chain adds
EFI/boot/grubx64.efifrom ubuntu-boot and ends inkernel.efi. - When a successful boot drops an old shim hash from modeenv, the next reseal also revokes the old TPM policies, so an older shim cannot be put back to reuse old sealed keys.
- snapd writes the firmware boot entry with the description
ubuntu, pointing atEFI/ubuntu/shimx64.efi, or atEFI/boot/bootx64.efiwhen only that one is installed.
Further reading
- Modify kernel options: the GRUB command line: mode arguments, the static part, gadget and system-option parts.
- Build a kernel snap: why a GRUB device needs the kernel and initrd bundled as
kernel.efi. - Storage layout: ubuntu-seed as the EFI system partition.
- Add a splash screen: a file listing of the pc gadget showing the signed shim and GRUB binaries.
- Full disk encryption: why shim, GRUB and the command line are measured.
Roads from here
UBUNTU CORE · boot
- From power-on to snapd — the whole run-mode boot through both GRUB stages
- Try, trying, done — what try and trying mean
- The kernel command line — how the command-line variables are filled
- Ubuntu Core: how a device boots and recovers — back to the Ubuntu Core overview
UBUNTU CORE · bootloaders
- Bootloaders: one interface, six implementations — the interface GRUB implements more of than any other
UBUNTU CORE · install and recovery
- Recovery systems — the systems the recovery menu lists
UBUNTU CORE · full disk encryption
- Sealed keys, boot chains and resealing — boot chains built from shim and GRUB and the kernel