ubuntu-seed and first boot
seed and seeding for Ubuntu Core developers for snapd developers
The ubuntu-seed partition holds one or more recovery systems. Each is a label with a model and assertions and shares one pool of snap files. On first boot snapd verifies the chosen system and installs its snaps in one change called Initialize system state which ends with mark-seeded. Preseeding does most of that work when the image is built.
On the map: ubuntu core install and recovery
01 A device that has never booted
Seeding is the change "Initialize system state": snapd installs the snaps of one recovery system from ubuntu-seed and ends by marking the system seeded. Install, recover and factory-reset mode seed their own temporary system the same way.
Your gateway has just come out of its box. It has snapd, but snapd's state is empty: no snaps installed, no model, nothing. So where does everything come from? From the seed partition, ubuntu-seed. It holds a recovery system: a model, its assertions, and the snap files. snapd reads that system, checks it, and installs its snaps. It does all of that as one ordinary change, initialize system state. That's seeding. When the last task finishes, the system is marked seeded, and only then do registration and refreshes start. The same thing happens, on a temporary filesystem, each time the device boots into install, recover or factory-reset mode.
02 Inside ubuntu-seed for Ubuntu Core developers for snapd developers
systems/<label>/ holds model and assertions/; asserted snaps are shared in the top-level snaps/ as <name>_<rev>.snap. Unasserted snaps, options.yaml and auto-import.assert are per system and honoured only for grade dangerous.
Mount the gateway's seed partition and look inside. Two directories matter. Systems has one directory per label, here 20260301. In it is a file with exactly the model, and a directory with every other assertion, but no model. Snaps, at the top, is a pool shared by every system, one file per snap-revision. So a second recovery system is cheap: its own label directory, the same files, plus the one kernel that changed. A system can also carry unasserted snaps and an options file, read only for grade dangerous. Before Ubuntu Core 20 there was one flat seed with a seed.yaml.
03 Nothing is trusted until it is checked for Ubuntu Core developers for snapd developers
The model must be exactly one; declarations and revisions must match one to one. Each snap blob is checked for size, SHA3-384 and provenance against its snap-revision. Above grade dangerous every snap must have a snap-id, and options.yaml and auto-import.assert are ignored.
A seed is just a partition, and anyone with a screwdriver can write to it. So snapd treats every file on it as a claim to check. First the model: exactly one, signed by the brand. Then the assertions must agree: one declaration per snap, one revision per snap-id, counts matching. Then each snap file, in order: size, SHA3-384 hash, provenance, all against its signed snap-revision. Above grade dangerous every snap needs a snap-id, and the extra files are ignored. With dangerous, an unasserted snap gets in as revision x1. Along the way, store signing times push a wrong clock forward.
04 Which snaps load in which mode for Ubuntu Core developers for snapd developers
Essential snaps load in every mode. Other model snaps load where their modes list says, run by default; ephemeral means every mode except run, factory-reset included. Extra snaps from options.yaml are run-mode only.
The recovery system on your gateway isn't only for recovery. The same label is used to install, recover, reset and run. So does every snap load every time? No, the model decides. Ephemeral is shorthand for every mode except run: install, recover and factory-reset. The four essential snaps load in all four. Any other snap names its modes, and the default is run only. So the agent is on the real system and absent while you recover. A diagnostics snap that lists run and recover shows up in both. Extra snaps that aren't in the model load in run mode only.
05 The seeding change, lane by lane for Ubuntu Core developers for snapd developers
The change "Initialize system state" installs the essential snaps in one lane (snapd, boot base, kernel, gadget) and the rest in another, configures core, the kernel and the gadget with gadget defaults, then runs enforce-validation-sets in run mode and mark-seeded last.
Run snap changes on the gateway's first boot and you'll see change one, initialize system state. Here's what's inside. The essential snaps go first, in their own lane, sorted by type: snapd, base, kernel, gadget. The base comes before the kernel so a kernel hook has a root filesystem, and the kernel isn't extracted again. Then configuration: the system first, then kernel and gadget, with the gadget's defaults. Everything else goes in a second lane. A lane is the unit of undo, so a failing app snap takes down only its own lane. Last, in run mode, validation sets are enforced, then mark-seeded.
06 What mark-seeded writes down for Ubuntu Core developers for snapd developers
mark-seeded clears recovery_system from modeenv in run mode, records the system in seeded-systems, makes it the default-recovery-system, and sets seed-time and seeded. snap debug seeding reports the outcome.
The snaps are installed. One small task is left, and the rest of the device's life leans on what it writes. In run mode it first clears the recovery system line from modeenv. That line was only there to get the first boot going. Then it records which system was seeded, and when. It also makes that system the default recovery system, so a device that comes back from a factory-reset points at the right one. Then it sets seeded, and the rest of snapd wakes up: registration, refreshes, the lot. Snap debug seeding shows you the result and how long it took.
07 Preseeding: seeding at the factory for Ubuntu Core developers for snapd developers
Preseeding stops the seeding change at mark-preseeded during the image build and ships preseed.tgz with a signed preseed assertion. Install applies it only if the signer is in the model's preseed-authority the label, model, brand and series match, and so do the digest and snaps.
Seeding takes time, and on a slow board your customer spends it watching a blank screen. Most of it comes out the same on every unit, so why not do it once, at build time? That's preseeding. snapd runs in a chroot, does the seeding work that needs no hooks, and stops at mark-preseeded. Out comes a tarball of system-data, without snap files, plus a preseed assertion with its digest and snap list. At the end of install, snapd checks the signer, then label, model, brand and series, then digest and snaps, and applies it. On first boot, mark-preseeded completes, hooks run, and mark-seeded finishes.
08 Where to go from here
Roads: the boot path, install mode, the modes, recovery systems, the model, snap assertions, changes and lanes, and snap debug.
That's a seed, and that's how it becomes a running system. Before snapd even starts, the boot path deck shows how the label and the mode reach it. Install mode is the first seeding a new device does, and it has its own deck, next to the one on the modes. Recovery systems shows how new labels get added to the seed later, and tested. The model deck explains the modes and grades the seed loader obeys, and the snap assertions deck explains the signatures it checks. Changes and lanes are covered in the town hall, and snap debug has a deck of its own.
Read more
for Ubuntu Core developers for snapd developers for administrators
The seed on disk (UC20 and later)
| Path under ubuntu-seed | What it is |
|---|---|
systems/<label>/model | exactly the model assertion |
systems/<label>/assertions/ | every other assertion; must contain no model |
systems/<label>/snaps/ | unasserted snaps of this system, with aux-info.json |
systems/<label>/options.yaml | extra snaps and options; grade dangerous only |
systems/<label>/auto-import.assert | system-user assertions loaded at first boot; grade dangerous only |
systems/<label>/preseed, preseed.tgz | the preseed assertion and the preseeded system data |
systems/<label>/snapd-new-file-log | written while a recovery system is being created, see Recovery systems |
snaps/<name>_<rev>.snap | asserted snaps, shared by every system |
At run time snapd reads the seed from /var/lib/snapd/seed; the label and the mode come from modeenv (recovery_system, mode).
for Ubuntu Core developers for snapd developers
Labels
- A label matches
^[a-z0-9](?:-?[a-z0-9])*$. - An image build uses the UTC date as
YYYYMMDD. - A remodel uses the date too and appends
-<n>if the label is taken. - A system created through the API takes the label the caller gives.
for Ubuntu Core developers for snapd developers
Checks when a seed is loaded
1. The model file holds exactly one model. 2. The number of snap-declarations equals the number of snap-revisions; the same holds for resource-revision and resource-pair assertions. 3. One declaration per snap name, one revision per snap-id. 4. Each snap file: size, then SHA3-384 against its snap-revision, then provenance. 5. Above grade dangerous, every snap is identified by snap-id. 6. Unasserted snaps (grade dangerous) get revision x1 and no channel.
dm-verity integrity data for seed snaps is looked up but not enforced.
snapd also raises its idea of "now" to the latest timestamp among the store-signed snap-revision and snap-declaration assertions and the model. Other assertions are ignored for this, since anyone could supply them.
for Ubuntu Core developers for snapd developers
The two seed formats
| seed16 (UC16, UC18, classic) | seed20 (UC20 and later) | |
|---|---|---|
| Chosen when | no label is given | a label is given |
| Layout | assertions/, seed.yaml, snaps/ | systems/<label>/ plus shared snaps/ |
| Model | exactly one in assertions/ | systems/<label>/model |
| Snap list | seed.yaml entries: name, snap-id, channel, devmode, classic, private, contact, unasserted, file | derived from the model, plus options.yaml for grade dangerous |
snap debug validate-seed | supported | not yet supported |
A missing seed.yaml is legitimate only on classic.
for Ubuntu Core developers for snapd developers
The seeding change
Change: "Initialize system state".
| Step | Notes |
|---|---|
| import assertions, set brand and model | from the seed's model |
| essential snaps, lane 1 | sorted by type with the boot base before the kernel; installed with configure and kernel extraction skipped |
| configure | core first, then kernel and gadget, with gadget defaults |
mark-preseeded | only when preseeding; sits between the pre-hook tasks and the hooks of every snap |
| other snaps, lane 2 | failures do not undo the essential snaps; bases and content providers are checked first |
enforce-validation-sets | run mode only; pins the sequences from the model |
mark-seeded | last; refuses to run while preseeding |
Devmode is applied automatically only for grade dangerous. With grade dangerous, auto-import.assert is loaded and all known system users are created as sudoers.
Errors when the seed and the system disagree: "cannot seed a classic system with an all-snaps model" and "can only seed an all-snaps system with a classic model in recovery mode".
Commands
| Command | Use |
|---|---|
snap changes, snap tasks 1 | watch the seeding change |
snap debug seeding | seeded, preseeded, image-preseeding, seed-completion, and seed-error if seeding failed |
snap debug validate-seed <seed.yaml> | validate a seed16 seed |
snap prepare-image --preseed --preseed-sign-key=<key> <model> <dir> | build a preseeded UC20+ seed; the image must contain exactly one system |
for Ubuntu Core developers for snapd developers
What preseed.tgz contains
A tar of the system data: snapd's state, the assertion database, AppArmor and seccomp profiles, the system key, systemd units, and the snap data directories. Snap and component files and the seed itself are excluded. The preseed assertion carries the tarball's digest and the list of snaps, and is signed with the key named by --preseed-sign-key (default default).
Further reading
- Storage layout: the seed's
systems/<label>directories and the shared snaps pool. - Optimise boot speed: what seeding does and how to build a preseeded image.
- Preseed performance: measured first-boot times with and without preseeding.
- Use ubuntu-image: how the seed is produced from a model.
- model assertion reference:
modes,presenceand the grade rules the seed follows.
Roads from here
RUNNING SNAPS
- The overlord — changes and tasks and lanes
ASSERTIONS · signed statements snapd trusts
- Assertions: snaps and validation — the snap-declaration and snap-revision assertions the seed is checked against
TOOLS
- snap debug: tools for looking inside — snap debug seeding and validate-seed
UBUNTU CORE · boot
- From power-on to snapd — how the initramfs picks the label and mode before snapd runs
- Run, install, recover, factory reset — what each mode mounts around the seeded system
- Ubuntu Core: how a device boots and recovers — back to the Ubuntu Core overview
UBUNTU CORE · install and recovery
- Install mode — install mode is the first system seeded on a new device
- Recovery systems — adding and removing systems on ubuntu-seed later
- Model, gadget and kernel — the model whose snaps and modes the seed follows
INSIDE SNAPD · the daemon itself
- Preparing images and preseeding — building the image