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

▶ Watch this deck — 8 scenes, ~6 min

01 A device that has never booted

FIRST POWER-ON ubuntu-seedrecovery system 20260301model + assertionssnap files reads, checkssnapd installed snapssnapdcore24pc-kernelpcacme-agent change: Initialize system state seededthen registration, refreshes install, recover and factory reset modes: the same seeding, on a temporary filesystem, at every boot
snapd reads and verifies a recovery system on ubuntu-seed, installs snapd, core24, pc-kernel, pc and acme-agent in the change Initialize system state, and marks the system seeded

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

ONE POOL, MANY SYSTEMS ubuntu-seed/ systems/20260301/the label modelassertions/exactly the modelthe rest, no model snaps/shared: name_rev.snapsnapd_25123.snapcore24_1587.snappc-kernel_2901.snappc_211.snapacme-agent_14.snap pc-kernel_2950.snap20261112/2026030120261112snaps/ poolsnapd · core24 · pc · acme-agentpc-kernel_2901pc-kernel_2950the second system adds one file snaps/options.yamlgrade dangerous only before UC20: one flat seed, seed.yaml, no labels
The ubuntu-seed file tree: systems/20260301 with model and assertions, a shared snaps pool of name_revision.snap files, and a second system 20261112 that reuses the pool and adds one kernel file

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

LOADING A SEED modelexactly one, signed by the brandotherwise: error assertionsone declaration per snap, one revision per snap-iddeclaration and revision counts matchotherwise: error pc-kernel_2901.snapsizeSHA3-384provenanceeach against its snap-revisionotherwise: error grade above dangerous?every snap needs a snap-id; options.yaml and auto-import.assert ignored grade dangerous: unassertedsnap accepted as x1 store-signed snap-revision and snap-declaration times, and the model's, raise snapd's idea of now
A chain of checks when a seed is loaded: one model signed by the brand, consistent assertions, size, SHA3-384 and provenance for each snap file, and a grade gate that only lets unasserted snaps through for grade dangerous

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

ONE SEED, FOUR MODES runinstallrecoverfactory-resetephemeralevery mode except run snapdloadedloadedloadedloadedpc-kernelloadedloadedloadedloadedcore24loadedloadedloadedloadedpcloadedloadedloadedloadedessential acme-agentdefault: [run]loaded--- acme-diag[run, recover]loaded-loaded- extra snapoptions.yamlloaded---extra snaps not in the model: grade dangerous only, run mode only
A grid of snaps against the modes run, install, recover and factory-reset: essential snaps load in all four, acme-agent only in run, acme-diag in run and recover, extra snaps from options.yaml only in run

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

INITIALIZE SYSTEM STATE $ snap changes1 Doing today at 09:02 UTC - Initialize system state lane 1: essentialsnapdcore24pc-kernelpcboot base before kernelnot extracted again configure coreconfigure pc-kernelconfigure pcwith gadget defaults lane 2: everything elseacme-agentfails: only this lane is undone enforce-validation-setsrun mode onlymark-seeded
The change Initialize system state: lane 1 installs snapd, core24, pc-kernel and pc in order and configures core, pc-kernel and pc; lane 2 installs acme-agent and is undone alone if it fails; enforce-validation-sets and mark-seeded come last

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

THE LAST TASK mark-seeded modeenvmode=runrecovery_system=20260301used once, to pick the system for the first run seeding snapd stateseeded-systems: [20260301, ...] default-recovery-system: 20260301matters after a factory reset seed-time: 2026-04-02 09:03 UTCseeded: trueregistration and refreshes may start $ snap debug seedingseeded: truepreseeded: falseseed-completion: 41.235s
mark-seeded clears recovery_system from modeenv, then writes seeded-systems, default-recovery-system, seed-time and seeded into snapd's state; snap debug seeding shows the result

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

DO IT ONCE, AT BUILD TIME image build on the device $ snap prepare-image --preseed \--preseed-sign-key=acme-key model.assert out/ snapd in a chrootinstall snaps, no hooksmark-preseededstops here systems/20260301/preseed.tgzsystem data, no snap filespreseedassertion: digest, snap list at the end of install, if:signer in the model's preseed-authoritylabel, model, brand, series matchdigest and snaps match first bootmark-preseeded completeshooks runmark-seeded
At image build snap prepare-image --preseed runs snapd in a chroot up to mark-preseeded and writes preseed.tgz and a preseed assertion; at the end of install they are checked and applied; on first boot the hooks run and mark-seeded finishes

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 ubuntu-seed and first boot The boot pathhow the label and mode arrive Install modethe first seedingThe modeswhat each mode mounts Recovery systemsnew labels, tested The modelmodes and gradesSnap assertionsthe signatures checked Changes and lanesthe town hallsnap debugseeding and validate-seed
Roads from ubuntu-seed and first boot: the boot path, install mode, the modes, recovery systems, the model, snap assertions, changes and lanes, and snap debug

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-seedWhat it is
systems/<label>/modelexactly 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.yamlextra snaps and options; grade dangerous only
systems/<label>/auto-import.assertsystem-user assertions loaded at first boot; grade dangerous only
systems/<label>/preseed, preseed.tgzthe preseed assertion and the preseeded system data
systems/<label>/snapd-new-file-logwritten while a recovery system is being created, see Recovery systems
snaps/<name>_<rev>.snapasserted 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 whenno label is givena label is given
Layoutassertions/, seed.yaml, snaps/systems/<label>/ plus shared snaps/
Modelexactly one in assertions/systems/<label>/model
Snap listseed.yaml entries: name, snap-id, channel, devmode, classic, private, contact, unasserted, filederived from the model, plus options.yaml for grade dangerous
snap debug validate-seedsupportednot 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".

StepNotes
import assertions, set brand and modelfrom the seed's model
essential snaps, lane 1sorted by type with the boot base before the kernel; installed with configure and kernel extraction skipped
configurecore first, then kernel and gadget, with gadget defaults
mark-preseededonly when preseeding; sits between the pre-hook tasks and the hooks of every snap
other snaps, lane 2failures do not undo the essential snaps; bases and content providers are checked first
enforce-validation-setsrun mode only; pins the sequences from the model
mark-seededlast; 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

CommandUse
snap changes, snap tasks 1watch the seeding change
snap debug seedingseeded, 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

Roads from here

RUNNING SNAPS

ASSERTIONS · signed statements snapd trusts

TOOLS

UBUNTU CORE · boot

UBUNTU CORE · install and recovery

INSIDE SNAPD · the daemon itself