Model, gadget and kernel

device definition for Ubuntu Core developers for snapd developers for administrators

Three documents define an Ubuntu Core device. The model assertion, signed by the brand, names the snapd, kernel, base and gadget snaps and sets the grade and storage-safety. The gadget's gadget.yaml lays out the disk by role and names the bootloader. The kernel's kernel.yaml offers assets the gadget can place on disk. A refresh rewrites a disk structure only when its edition goes up.

On the map: ubuntu core install and recovery

▶ Watch this deck — 8 scenes, ~6 min

01 Three documents, one device

WHO DECIDES WHAT THIS DEVICE IS model assertionacme-gatewaysigned by the brand: acme essential snapssnapdpc-kernel (kernel)core24 (base)pc (gadget) disk layout + bootloaderdescribed by the gadget kernel, initramfsboot files offered to the gadget You can refresh these snaps. You cannot swap them without a new model.
The acme-gateway model assertion, signed by the brand acme, names four essential snaps: snapd, pc-kernel, core24 and pc. The pc gadget describes the disk layout and bootloader; pc-kernel carries the kernel and initramfs and offers boot files to the gadget. The snaps refresh, but replacing one needs a new model.

The model assertion is signed by the brand and names the essential snaps: snapd, the kernel, the base and the gadget. The gadget and kernel snaps describe the disk layout, the bootloader and the kernel's boot files. They refresh normally; replacing one with a different snap needs a new model.

Somebody has to decide what your gateway is: which kernel it runs, how its disk is cut up, which store it talks to. On Ubuntu Core that's the brand, and the decision is a signed document called the model. Ours is acme-gateway, signed by acme. It names four essential snaps: snapd, the kernel, the base and the gadget. The gadget snap lays out the disk and picks the bootloader. The kernel snap brings the kernel and initramfs, and can offer files for the gadget to place. All four refresh like any snap; swapping one for a different snap takes a new model.

02 What snap model tells you

ASK THE DEVICE $ snap model brandAcme Corp (acme)modelAcme Gateway (acme-gateway)display-name (model) gradesecuredno storage-safety line: the modeldoes not set it, so the default applies serial0b7c7a2e-...before registration:serial - (device not registered yet) $ snap model --assertionthe signed text$ snap model --serialbrand, model, serial
A terminal running snap model on acme-gateway: brand Acme Corp (acme), model Acme Gateway (acme-gateway), grade secured, no storage-safety line because the model does not set it, and the serial, which is a dash before registration. Below, snap model --assertion and snap model --serial.

snap model prints brand, model, grade, storage-safety and serial. Grade and storage-safety appear only when the header is present in the model, so defaults are not shown. --assertion prints the raw signed assertion and --serial the brand, model and serial.

You're logged in to a gateway somebody else built. Which model is it? Ask it: snap model. No sudo needed. First comes the brand, then the model, shown as its display name with the real name in brackets. Then the grade. Grade and storage-safety appear only when the model sets them. Ours leaves storage-safety out, so there's no line for it, and that means the default, not none. Last is the serial, the device's own identity; before registration you get a dash. Want the signed text itself? Run snap model --assertion. And snap model --serial shows the serial side.

03 Inside the model assertion for Ubuntu Core developers for snapd developers

THE EXTENDED FORM type: modelauthority-id: acmebrand-id: acmemodel: acme-gatewayseries: 16signed by the brand:authority-id must equal brand-id architecture: amd64base: core24grade: securedrequired in the extended form(Ubuntu Core 20 and later) snaps:- name: pctype: gadgetdefault-channel: 24/stableid: <snap-id>pc-kernel, core24, snapd: the same shapereplaces the old gadget and kernel headers;exactly one gadget and one kernel entry;id may be left out only on grade dangerous - name: acme-diagmodes: [run, recover]presence: optionalleft out: modes means run,presence means required essential snaps: no modes, no presencealways there: run, install, recover, factory-reset
The headers of the acme-gateway model assertion: type, authority-id and brand-id acme, model, architecture amd64, base core24, grade secured, and a snaps list with the pc gadget entry and the acme-diag entry with modes run and recover and presence optional. Callouts explain each part and that essential snaps cannot set modes or presence.

The UC20+ model lists its snaps. authority-id must equal brand-id. id is mandatory above grade dangerous, default-channel defaults to latest/stable, modes to run and presence to required. Essential snaps may set neither modes nor presence.

Here's acme-gateway's model with the signature cut off. Authority and brand must be the same account: a brand signs its own models. This is the extended form, used from ubuntu-core20 on. It needs an architecture and a base, and instead of separate gadget and kernel headers it has a snaps list, with exactly one gadget and one kernel. Each entry has a name, a type, a default channel and an id, which only a dangerous model may leave out. Our diagnostics snap sets modes and presence; left out, they mean run and required. Essential snaps can't set either. They're always there, in every mode.

04 Grade, how strict the device is for Ubuntu Core developers for snapd developers for administrators

ONE WORD, MANY CONSEQUENCES dangeroussignedthe defaultsecuredacme-gateway snaps without an idunasserted kernel or gadgetseed extras: options, auto-importcmdline outside the allow list none of thesenone of these storage-safety defaultprefer-encryptedprefer-encryptedencrypted anything else in storage-safety:model rejected A remodel cannot change the grade.
Three grades side by side: dangerous, signed (the default) and secured. Only dangerous allows snaps without ids, an unasserted kernel or gadget, seed extras and kernel arguments outside the allow list. The storage-safety default is prefer-encrypted for dangerous and signed and encrypted for secured, where any other value is rejected. A remodel cannot change the grade.

grade is dangerous, signed (the default) or secured. storage-safety defaults to encrypted for secured and prefer-encrypted otherwise; a secured model may not set anything but encrypted. A remodel cannot change the grade.

One header in the model sets the tone for everything else: grade. There are three values, and signed is the default. Dangerous is for development. It lets you list snaps without ids, swap in an unsigned kernel or gadget, put extra configuration and assertions in the seed, and append kernel arguments the gadget doesn't allow. Signed and secured allow none of that. Grade also sets the default storage-safety: must the disk be encrypted? Secured means encrypted, and a secured model that says otherwise is rejected. The other two default to prefer-encrypted. What install does with that is the encryption deck's story. And no remodel can change the grade.

05 The gadget lays out the disk for Ubuntu Core developers for snapd developers

ROLES, NOT NAMES pc: gadget.yamlvolumes:pc:schema: gptone volume = one disk bootloader: grubexactly one volume names a bootloader structure:- name: ubuntu-seedrole: system-seedfilesystem: vfat- name: ubuntu-bootrole: system-boot- name: ubuntu-saverole: system-save- name: ubuntu-datarole: system-datambr and BIOS boot structures left outsystem-seedsystem-bootsystem-savesystem-data label when none is written:ubuntu-seedubuntu-bootubuntu-saveubuntu-data a model with a grade needs system-seed and system-dataencrypted data needs system-save boot, save and data must share the seed's volume
The pc gadget.yaml: one volume pc with schema gpt and bootloader grub, and four structures with roles system-seed, system-boot, system-save and system-data. A disk bar shows the four partitions and the labels they get from their roles: ubuntu-seed, ubuntu-boot, ubuntu-save and ubuntu-data. Rules: a model with a grade needs system-seed and system-data, encrypted data needs system-save, and all must be on the seed's volume.

role decides what a structure is for and its default label: system-seed, system-boot, system-save and system-data become ubuntu-seed, ubuntu-boot, ubuntu-save and ubuntu-data. Exactly one volume declares the bootloader.

The model says which gadget. The gadget says what the disk looks like. Its gadget.yaml describes volumes. A volume is one disk: a partition schema and, on exactly one volume, the bootloader. Ours is GPT with GRUB. What counts about each structure is its role, not its name. Our gateway has four: system-seed, system-boot, system-save and system-data. Since Ubuntu Core 20, an unlabelled structure takes its label from its role: ubuntu-seed, ubuntu-boot, ubuntu-save, ubuntu-data. snapd checks the gadget against the model. A model with a grade needs seed and data, encrypted data needs save, and all share the seed's volume.

06 The kernel offers, the gadget places for Ubuntu Core developers for snapd developers

TWO SNAPS, ONE PARTITION kernel snap: kernel.yamlassets:dtbs:update: truecontent:- dtbs/ gadget.yaml (one structure)content:- source: $kernel:dtbs/dtbs/target: / ubuntu-seed (system-seed)written at install, rewritten on a kernel refresh update: true and no structure consumes it:the new kernel is refusedgadget does not consume any of the kernelassets needing synced update
On an Arm board that needs device trees, the kernel's kernel.yaml names an asset dtbs with update true, and a gadget.yaml structure takes its content from $kernel:dtbs/dtbs/. The files land on ubuntu-seed at install and are rewritten on a kernel refresh. A kernel with an update-true asset that no gadget structure consumes is refused.

kernel.yaml assets have update and content; gadget content refers to them as $kernel:<asset>/<path>. A kernel refresh rewrites only content from update: true assets and is refused if no structure consumes one. When one reboot serves several snaps the restart order is os, base, gadget, kernel: the gadget may define new $kernel: references, so it goes first.

Our gateway's pc gadget has no $kernel references, but Arm boards do: they need device trees from the kernel snap on a boot partition. Who owns those files, the kernel or the gadget? Both. On such a board, kernel.yaml names an asset, dtbs, with its content. The gadget pulls it into a structure with $kernel, colon, the asset name and a path. Only assets marked update: true are rewritten when the kernel refreshes. If no gadget structure consumes one, snapd refuses the new kernel: its files would never reach the disk, and the board might not boot.

07 What a refresh may rewrite for Ubuntu Core developers for snapd developers for administrators

A GADGET REFRESH, STEP BY STEP $ snap refresh pctask: update-gadget-assets update edition, old → newubuntu-seed 2 → 3ubuntu-boot 1 → 1mbr 0 → 0only a higher edition is selected same role, id, filesystem, label?no volume added or removed?no: refresh fails,nothing written back up allwrite eachfirst failure: roll backevery structure touched restart requestednothing selected: "nothing to update", the refresh succeeds, no restart from this task other policies: a remodel rewrites every structure but the mbr;a kernel refresh rewrites only the kernel's update: true assets
A gadget refresh: snap refresh pc runs the update-gadget-assets task. Only structures whose edition went up are selected, here ubuntu-seed from 2 to 3. Each selected structure must keep its role, id, filesystem and label or the refresh fails before anything is written. Structures are backed up and written, and the first failure rolls all of them back. Success requests a restart; with nothing selected the refresh succeeds without one.

The default policy rewrites a structure only when its update.edition increased. Selected structures are checked, backed up, written, and rolled back together on the first failure. "Nothing to update" counts as success and requests no restart.

A new gadget revision lands on your gateway. Does snapd rewrite the boot partitions? Only if the gadget's author asked. The ask is a number, the edition, on each structure. Higher than before: rewrite it. The same: leave it alone. Before anything is written, each selected structure is checked: its role, id, filesystem and label can't change, and volumes can't come or go. Then they're backed up and written, and the first failure rolls them all back. Success asks for a restart. If nothing was selected, the refresh still succeeds without one. A remodel rewrites every structure but the MBR; a kernel refresh touches only the kernel's assets.

08 Where to go from here

ROADS model, gadget, kernel Install modethe layout becomes partitionsThe seedwhere the model and snaps wait Encryptionwhat storage-safety decides Kernel command linethe gadget's settingsBootloaderswhat the gadget's choice means Factory reset and remodela new model on a live device Assertionsthe model and serial, signed Device hooksinstall and registration
Roads from model, gadget and kernel: install mode and the seed, encryption, the kernel command line and bootloaders, factory reset and remodel, and the assertions and device hooks.

Roads to install mode, the seed, encryption, the kernel command line, bootloaders, factory reset and remodel, the assertions and the device hooks.

You know who defines the device. Next, watch that definition become a disk. Install mode turns the gadget's layout into partitions, and the seed deck shows where the model and its snaps wait before that. Grade and storage-safety pay off in the encryption decks. The gadget's kernel command line and its bootloader each have a deck. To change the model on a running device, go to factory-reset and remodel. The model as a signed document is in the assertions district, and the hooks a gadget runs at install and registration are in the hooks district.

Read more

Commands

CommandWhat it shows or does
snap modelbrand, model, grade and storage-safety (only if set in the model), serial
snap model --verboseevery header, starting with brand-id and model
snap model --serialbrand-id, model, serial; fails with "device not registered yet (no serial assertion found)" before registration
snap model --assertionthe raw signed assertion; not combinable with --verbose
snap known model, snap known serialthe same assertions from the assertion database
snap remodel <new model file>replace the model; see Factory reset, ubuntu-save and remodel

What you cannot do without a new model

  • Install a kernel or gadget other than the one the model names: "cannot install %s %q, model assertion requests %q".
  • Replace the kernel or gadget with a different snap: "cannot replace %s snap with a different one".
  • Replace a signed kernel or gadget with an unasserted one, unless the grade is dangerous.
  • Install a kernel or gadget published by anyone but canonical or the brand.

for Ubuntu Core developers for snapd developers

Model headers

HeaderNotes
series, brand-id, modelthe primary key; authority-id must equal brand-id
architecture, baserequired in the extended (UC20+) form
snapsthe extended form; excludes the old gadget, kernel and required-snaps headers
gradedangerous, signed (default), secured
storage-safetyencrypted, prefer-encrypted, prefer-unencrypted; default encrypted for secured, else prefer-encrypted
storeempty means the default store
display-name, timestampshown by snap model; signing time
classic, distributionclassic: true with snaps is a hybrid model and needs distribution
validation-setsentries with account-id (default the brand), name, optional sequence, mandatory mode: enforce or prefer-enforce
serial-authorityaccounts besides the brand that may sign serials
preseed-authorityaccounts that may sign the preseed assertion
system-user-authorityaccounts that may sign system-user assertions; the only one that accepts *

for Ubuntu Core developers for snapd developers

A snaps entry

KeyDefaultNotes
nameno duplicates by name or id
idmandatory unless the grade is dangerous
typeappapp, base, gadget, kernel, core, snapd
default-channellatest/stablemust specify a track
presencerequiredor optional; not allowed on essential snaps
modesrunnot allowed on essential snaps, which are in run and in every ephemeral mode
classicclassic models only, app snaps only, run mode only
componentsname to required/optional, or a map with presence and modes (a subset of the snap's modes)

The grade is measured for full disk encryption as a number: dangerous 0x10000, signed 0x80000, secured 0x100000.

for Ubuntu Core developers for snapd developers

gadget.yaml at a glance

Top level: volumes, volume-assignments, defaults, connections, kernel-cmdline.

Volume keyValues
schemagpt (default), mbr, emmc
bootloadergrub, u-boot, piboot (UC20 onwards), lk, android-boot; on exactly one volume
id2-hex-digit disk id or GPT GUID
partialsize, filesystem, schema, structure: left for an installer to fill in
structurethe list below

Structure keys: name, filesystem-label, offset, offset-write, min-size, size, type, role, id, filesystem (ext4, vfat, vfat-16, vfat-32, none), content, update (edition, preserve).

RoleDefault label (UC20+)Notes
system-seedubuntu-seedrequired by a model with a grade
system-seed-nullubuntu-seedhybrid classic only; excludes system-seed
system-bootubuntu-bootcreatable at install
system-saveubuntu-savecreatable at install; required for encrypted data
system-dataubuntu-datacreatable at install; labelled writable on models without modes
mbrat most 446 bytes at offset 0
system-boot-stateraw, explicit offset, at least 1 MiB
system-boot-image, system-seed-image, system-boot-select, system-seed-selectused by the Little Kernel bootloader, see Little Kernel

At most one structure of each system role per gadget. The four ubuntu- labels are reserved on models with modes.

for Ubuntu Core developers for snapd developers

Update policies

PolicyUsed forSelects
defaulta gadget refreshstructures whose update.edition increased
remodela gadget arriving in a remodelevery structure except the mbr role
kernelany kernel refresh, also inside a remodelstructures with a $kernel: source, and in them only content from update: true assets

A selected structure may not change: its name (on GPT), role, id, type, filesystem (undefined to defined is allowed), filesystem label, or between bare and filesystem; old and new size and offset ranges must overlap. Volumes cannot be added or removed, and the volume id and structure count stay the same. Boot structures are updated before seed structures. Locations come from the disk-mapping.json written at install; without it only the system-boot volume is updated.

Refresh tasks that touch the disk: update-gadget-assets (gadget and kernel), update-gadget-cmdline (gadget), prepare-kernel-snap (kernels that need a drivers tree).

for Ubuntu Core developers for snapd developers

kernel.yaml

KeyMeaning
assets.<name>.updatetrue: rewrite this asset's content on disk when the kernel refreshes
assets.<name>.contentlist of paths in the kernel snap
dynamic-modulesonly $SNAP_DATA is accepted; a folder with modules and firmware built by hooks

Kernel modules can also arrive as kernel-modules components. snapd builds a drivers tree per kernel revision and can swap a component's modules into a running kernel's tree without a reboot.

for Ubuntu Core developers for snapd developers for app developers

Gadget defaults and connections

  • defaults is keyed by snap-id or by system. A snap's defaults are applied before its configure hook on first install; a snap with defaults and no configure or default-configure hook fails to install. See configure hooks.
  • connections lists plug and an optional slot, each as <snap-id>:name or system:name. They are applied only during seeding or a remodel, and they obey the connection rules of the declarations, not the auto-connection rules.

Further reading

Roads from here

ASSERTIONS · signed statements snapd trusts

HOOKS · code snapd runs inside a snap

UBUNTU CORE · boot

UBUNTU CORE · bootloaders

UBUNTU CORE · install and recovery

UBUNTU CORE · full disk encryption