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
01 Three documents, one device
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
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 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
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
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
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
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 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
| Command | What it shows or does |
|---|---|
snap model | brand, model, grade and storage-safety (only if set in the model), serial |
snap model --verbose | every header, starting with brand-id and model |
snap model --serial | brand-id, model, serial; fails with "device not registered yet (no serial assertion found)" before registration |
snap model --assertion | the raw signed assertion; not combinable with --verbose |
snap known model, snap known serial | the 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
| Header | Notes |
|---|---|
series, brand-id, model | the primary key; authority-id must equal brand-id |
architecture, base | required in the extended (UC20+) form |
snaps | the extended form; excludes the old gadget, kernel and required-snaps headers |
grade | dangerous, signed (default), secured |
storage-safety | encrypted, prefer-encrypted, prefer-unencrypted; default encrypted for secured, else prefer-encrypted |
store | empty means the default store |
display-name, timestamp | shown by snap model; signing time |
classic, distribution | classic: true with snaps is a hybrid model and needs distribution |
validation-sets | entries with account-id (default the brand), name, optional sequence, mandatory mode: enforce or prefer-enforce |
serial-authority | accounts besides the brand that may sign serials |
preseed-authority | accounts that may sign the preseed assertion |
system-user-authority | accounts that may sign system-user assertions; the only one that accepts * |
for Ubuntu Core developers for snapd developers
A snaps entry
| Key | Default | Notes |
|---|---|---|
name | no duplicates by name or id | |
id | mandatory unless the grade is dangerous | |
type | app | app, base, gadget, kernel, core, snapd |
default-channel | latest/stable | must specify a track |
presence | required | or optional; not allowed on essential snaps |
modes | run | not allowed on essential snaps, which are in run and in every ephemeral mode |
classic | classic models only, app snaps only, run mode only | |
components | name 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 key | Values |
|---|---|
schema | gpt (default), mbr, emmc |
bootloader | grub, u-boot, piboot (UC20 onwards), lk, android-boot; on exactly one volume |
id | 2-hex-digit disk id or GPT GUID |
partial | size, filesystem, schema, structure: left for an installer to fill in |
structure | the 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).
| Role | Default label (UC20+) | Notes |
|---|---|---|
system-seed | ubuntu-seed | required by a model with a grade |
system-seed-null | ubuntu-seed | hybrid classic only; excludes system-seed |
system-boot | ubuntu-boot | creatable at install |
system-save | ubuntu-save | creatable at install; required for encrypted data |
system-data | ubuntu-data | creatable at install; labelled writable on models without modes |
mbr | at most 446 bytes at offset 0 | |
system-boot-state | raw, explicit offset, at least 1 MiB | |
system-boot-image, system-seed-image, system-boot-select, system-seed-select | used 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
| Policy | Used for | Selects |
|---|---|---|
| default | a gadget refresh | structures whose update.edition increased |
| remodel | a gadget arriving in a remodel | every structure except the mbr role |
| kernel | any kernel refresh, also inside a remodel | structures 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
| Key | Meaning |
|---|---|
assets.<name>.update | true: rewrite this asset's content on disk when the kernel refreshes |
assets.<name>.content | list of paths in the kernel snap |
dynamic-modules | only $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
defaultsis keyed by snap-id or bysystem. 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.connectionslistsplugand an optionalslot, each as<snap-id>:nameorsystem:name. They are applied only during seeding or a remodel, and they obey theconnectionrules of the declarations, not theauto-connectionrules.
Further reading
- model assertion reference: every header with a full example.
- Gadget snap format: the annotated gadget.yaml specification.
- The kernel snap: kernel.yaml and
$kernel:references. - Build a gadget snap: a template gadget.yaml and how to build it.
- Build your first image: writing and signing a model end to end.
Roads from here
ASSERTIONS · signed statements snapd trusts
- Assertions: how they work — the model is an assertion
- Assertions: devices — the model and serial assertions header by header
HOOKS · code snapd runs inside a snap
- Hooks: device setup — the gadget hooks that run during install and registration
UBUNTU CORE · boot
- The kernel command line — the gadget's kernel command line settings
- Ubuntu Core: how a device boots and recovers — back to the Ubuntu Core overview
UBUNTU CORE · bootloaders
- Bootloaders: one interface, six implementations — what the gadget's bootloader choice means at boot
UBUNTU CORE · install and recovery
- Install mode — how install mode turns the gadget's layout into partitions
- ubuntu-seed and first boot — the recovery system that carries the model and its snaps
- Factory reset, ubuntu-save and remodel — replacing the model on a running device
- A device set up before anyone logs in — a device set up before anyone logs in
UBUNTU CORE · full disk encryption
- What is encrypted and who decides — what grade and storage-safety decide about encryption