Snap components

optional parts of the snap for users for CI operators

A snap component is an optional part of a snap, published with it and tied to its revision. The image-garden snap ships each QEMU, pkgproxy, swtpm, spread and spread-plus as one; its hooks install QEMU for the host, pkgproxy and spread, stubs and make name the command for the rest, and a snap installed from a file gets none.

On the map: snap

▶ Watch this deck — 7 scenes, ~5 min

Worth seeing first

01 One snap, optional parts

ONE SNAP, OPTIONAL PARTS image-garden snap qemu-x86-64 qemu-aarch64 qemu-riscv64 qemu-s390x qemu-ppc64 qemu-loongarch64 qemu-x86-64 a component: installed on its own published with the snap tied to its revision qemu-aarch64 $ snap install image-garden+qemu-aarch64 The snap stays small; each user adds only the parts they need.
The image-garden snap with six QEMU components beside it; only qemu-x86-64 and, after snap install image-garden+qemu-aarch64, qemu-aarch64 are installed; a component is a separately installed part, published with the snap and tied to its revision, so the snap stays small

A component is an optional part of a snap, published with it and tied to its revision. snap install image-garden+qemu-aarch64 adds one.

Most people who use snaps have never met a component, so let's start there. Say you test on a PC. You need QEMU for x86_64, and maybe never for RISC-V or s390x. Putting all six emulators in the snap would make every user download all six. A snap component solves that. It's a part of a snap that you install separately, built and published together with the snap, and tied to its revision. You add one with snap install image-garden+qemu-aarch64. The snap stays small, and each user adds only the pieces they need. This deck explains the feature first, then image-garden's components and how they arrive.

Details and sources

Details

  • The snap declares ten components, all type: standard: spread, spread-plus, six qemu-<arch>, pkgproxy and swtpm (snapcraft.yaml:45-119).
  • The README's section on them: "Install only the CPU architectures you need", with snap install image-garden+qemu-aarch64 as the manual way (README.md:309-320).
  • Derived, from snapd rather than image-garden's tree: a component is built and uploaded with its snap's revision and can only be installed for the revision it was built with. The snapd map's Components deck covers how snapd installs, refreshes and removes them.

Read more

02 How a component behaves

HOW A COMPONENT BEHAVES snapcraft.yaml components: swtpm: … snap, revision R swtpm, revision R spread, revision R uploaded together; on refresh, the snap and the components you have move together $ snap install image-garden+swtpm $ snap components image-garden $ snapctl install +pkgproxy from the snap's own hook /snap/image-garden/components/R/swtpm where the snap's programs look
Components are declared in snapcraft.yaml and uploaded with each snap revision; they refresh with the snap; snap install image-garden+swtpm adds one, snap components lists them, and a hook can run snapctl install +pkgproxy; on the machine each lives under /snap/image-garden/components/REVISION/

Declared in snapcraft.yaml and uploaded with each revision. snap install image-garden+swtpm adds one, snap components image-garden lists them, and they refresh with the snap.

Here's how a component behaves. It's declared in the same snapcraft.yaml as its snap, built with it and uploaded with each revision, so it always matches the snap it belongs to. When the snap refreshes, the components you have refresh with it. You install one with snap install and a plus, and snap components lists what's installed and what's available. A snap can also ask for its own, from a hook, with snapctl install +pkgproxy. On your machine, snapd puts each component in a directory named after the snap's revision, where the snap's programs look for it.

Details and sources

Details

  • Each component has a name, a type, a summary, a description and a version in snapcraft.yaml; snapcraft's organize puts a part's files into (component/NAME)/ (snapcraft.yaml:45-119, snapcraft.yaml:419-425).
  • The snap's programs find a component at $SNAP/../components/$SNAP_REVISION/NAME, that is /snap/image-garden/components/REVISION/NAME (qemu-system-x86_64:9-36).
  • A hook asks for components with snapctl install +NAME (install:13).
  • "On refresh, spread components are automatically updated" (README.md:179).
  • Derived, from snapd (cmd/snapd/cli/cmd_components.go, overlord/hookstate/ctlcmd/install.go): snap components lists the installed and available components of installed snaps; snap remove image-garden+swtpm removes one; snapctl install accepts +comp or snap+comp for the calling snap only. The revision R on the slide stands for any revision number.

Read more

03 image-garden's ten components

TEN COMPONENTS image-garden snap qemu-x86-64 qemu-aarch64 qemu-riscv64 qemu-s390x qemu-ppc64 qemu-loongarch64 QEMU and its machines' firmware qemu-x86-64 x86-64 also: the Secure Boot OVMF pair pkgproxy with pkgproxyctl swtpm spread spread-plus image-garden, make rules qemu-img, make, curl, virtiofsd a stub per program
The image-garden snap in the middle, keeping image-garden, its make rules, qemu-img, make, curl, virtiofsd and the stubs; six QEMU components on the left, qemu-x86-64 also with the Secure Boot OVMF; pkgproxy with pkgproxyctl, swtpm, spread and spread-plus on the right

Six qemu-arch components, pkgproxy, swtpm, spread and spread-plus. The snap itself keeps image-garden, qemu-img, the tools, virtiofsd and the stubs.

So what does image-garden split off? Ten components, all declared in its snapcraft.yaml. Six carry QEMU, one per architecture, each with the firmware its machines load, from qemu-x86-64 to qemu-loongarch64. The x86 one also holds the Secure Boot firmware. pkgproxy has its own component, with its control tool. swtpm, the TPM emulator, has one. And the two test runners, spread and spread-plus, are one each. What stays in the snap itself is small: image-garden and its make rules, qemu-img, make, curl, virtiofsd, and a stub for every program that lives in a component.

Details and sources

Details

Read more

04 Which arrive on their own

WHO INSTALLS WHAT on a snap from the store, three hooks install hook +qemu-<host> +pkgproxy configure hook +spread or +spread-<variant> +pkgproxy, if set back runs at install, at every refresh, after every snap set post-refresh hook missing +qemu-<host> or +pkgproxy A hook's snapctl install is queued: it finishes after the hook. by hand: the other five QEMUs, and swtpm
The install hook installs +qemu for the host and +pkgproxy; the configure hook, run at install, refresh and every snap set, installs +spread or +spread-variant and +pkgproxy when set back; the post-refresh hook puts back a missing host QEMU or pkgproxy; requests from hooks are queued; the other QEMUs and swtpm are installed by hand

install: +qemu-host, +pkgproxy. configure: +spread or +spread-variant. post-refresh: whatever of the first two is missing. By hand: the other QEMUs and swtpm.

Which of the ten arrive by themselves? On a snap from the store, three hooks decide. The install hook asks for QEMU for your machine's architecture, and for pkgproxy. The configure hook, which snapd runs at install, at every refresh and after every snap set, adds spread, or the spread variant you chose, and pkgproxy again if you switch back to it. After a refresh, the post-refresh hook puts back your QEMU and pkgproxy if they're missing. A hook's request is queued, and finishes after the hook itself. The rest is yours to add when you need it: the other five QEMUs, and swtpm.

Details and sources

Details

  • install: snapctl install +qemu-$(uname -m) (with _ as -) +pkgproxy, unless the revision is a local one (install:6-14).
  • configure: with spread-variant empty it installs +spread when components/REVISION/spread/spread is missing; with a variant, +spread-VARIANT (configure:83-107). With pkgproxy set (not unset) to component or true and the component missing, it installs +pkgproxy (configure:41-55).
  • post-refresh: the host's QEMU component if its directory is missing, and +pkgproxy when pkgproxy is unset, true or component and the component is missing (post-refresh:9-29).
  • "snapctl install, called from the install or post-refresh hook, only queues the component for after the hook" (qemu-stubs/pkgproxy:6-10). snapd queues every snapctl install run from a hook (derived, overlord/hookstate/ctlcmd/helpers.go in snapd).
  • Derived, from snapd: the configure hook runs at install, after the install hook, at refresh and after snap set. So a store install ends with three components: the host's QEMU, pkgproxy and spread.
  • The README says so: the snap "installs the standard variant, image-garden+spread, as it is installed: its configure hook runs as root then, and installs the component that the spread-variant setting names, the standard one while it is empty" (README.md:163-169). An older entry of the snap's news, "When not using spread they are not installed" (NEWS.snappy:278-279), no longer holds.

05 When a component is missing

WHEN ONE IS MISSING stubs: qemu-system-* swtpm pkgproxy pkgproxyctl ┌──────────── Notice ────────────┐ Install the component with the following command: snap install image-garden+qemu-riscv64 the stub, when it runs install qemu-aarch64 component to use aarch64 emulation make, before the firmware install the swtpm component to use systems with a TPM: snap install image-garden+swtpm make, before a +tpm download pkgproxy service waits for its component, checking every 5 s
The snap has stubs for qemu-system-*, swtpm, pkgproxy and pkgproxyctl; a QEMU stub without its component shows a message with snap install image-garden+qemu-riscv64; make checks earlier with install qemu-aarch64 component to use aarch64 emulation and, for a +tpm system, snap install image-garden+swtpm; the pkgproxy service waits for its component

Stubs stand in for QEMU, swtpm, pkgproxy and pkgproxyctl. make checks first where it can: install qemu-aarch64 component to use aarch64 emulation. The pkgproxy service waits for its component.

What if a component isn't there? Every program that lives in one has a small stub in the snap itself, so the command always exists. Run QEMU for an architecture you haven't installed, and its stub shows a message with the exact snap install command. make often notices sooner. Before it copies the firmware for an aarch64 system, it says install qemu-aarch64 component to use aarch64 emulation. A +tpm system stops before its download, with snap install image-garden+swtpm. One stub waits instead of failing: the pkgproxy service's, because its component may still be on its way.

Details and sources

Details

  • Each QEMU stub tests $SNAP/../components/$SNAP_REVISION/qemu-<arch> and, without it, shows a message headed Notice ending in snap install image-garden+qemu-<arch> and exits 1 (qemu-system-x86_64:9-31); the riscv64 stub is the same with its names. The swtpm and pkgproxyctl stubs do the same for their components (swtpm:11-32, pkgproxyctl:6-27).
  • make's check: install qemu-aarch64 component to use aarch64 emulation (010-qemu.mk:50-55), run before the firmware copies of x86_64, aarch64, riscv64 and loongarch64 (010-qemu-aarch64.mk:93-99, 010-qemu-x86_64.mk:310-316). s390x and ppc64 copy no firmware, so for them the stub is the first to notice.
  • The swtpm check: install the swtpm component to use systems with a TPM: snap install image-garden+swtpm (010-qemu-x86_64.mk:124-131), an order-only prerequisite of each +tpm download link, so it fails before the download (050-ubuntu-core.mk:74-79, 050-ubuntu-core.mk:279-289).
  • The pkgproxy stub prints pkgproxy: waiting for the pkgproxy component and checks every 5 seconds, so that restart-condition: always does not crash-loop (qemu-stubs/pkgproxy:6-18).

06 A snap from a file gets none

SIDELOADED $ snap install --dangerous ./image-garden_*.snap revision x1 the store every hook skips its snapctl install $ snap install --dangerous ./image-garden+pkgproxy_*.comp $ snap install --dangerous ./image-garden+swtpm_*.comp or from the store: the hooks do it
A snap installed from a file with snap install --dangerous gets revision x1; every hook skips snapctl install because there is no store behind it; install the .comp files the same way, or install the snap from the store and let the hooks do it

A sideloaded revision (x1, x2…) installs no components. Install them from their files: snap install --dangerous ./image-garden+pkgproxy_*.comp.

There's one case where none of this happens. When you build the snap yourself and install the file with snap install --dangerous, its revision starts with an x, like x1. Every hook checks for that and skips its snapctl install, because a local revision has no store behind it to fetch components from. So install the components from files too. snapcraft builds a .comp file for each one next to the snap, and you install the one for pkgproxy, and any other you need, the same way, with snap install --dangerous. Or install the snap from the store, and let the hooks do it.

Details and sources

Details

  • Every hook skips snapctl install when $SNAP_REVISION matches x[0-9]+: install (install:6), post-refresh (post-refresh:9) and configure for pkgproxy and spread (configure:49, configure:87, configure:102).
  • The README: "A locally built snap, installed with --dangerous, cannot fetch it from the store: install the component built alongside it with snap install --dangerous ./image-garden+pkgproxy_*.comp" (README.md:228-232).
  • Derived, from snapd: a revision installed from a file gets a local revision, x1, x2 and so on, and has no store revision whose components could be fetched.
  • The spread app is not a hook and does not check the revision. When a component a project asks for is missing, it runs snapctl install only as root, which on a sideloaded snap has nothing to fetch either; then it stops with a message and the snap install image-garden+COMPONENT command (spread-chooser:35-49). For a sideloaded snap, install the component's .comp file instead.

Read more

07 Where to go from here

ROADS Components swtpm in the snap and the Secure Boot pair Choosing a spread spread or spread-plus pkgproxy= setting the default proxy, or another snapd map: Components optional, the feature in snapd also: the snap overview, confinement
Roads from the components deck: swtpm and Secure Boot firmware, choosing a spread, the pkgproxy setting, and optionally the snapd map's Components deck; also the snap overview and confinement

Next: swtpm and the Secure Boot firmware, choosing a spread, the pkgproxy setting, the snap overview, confinement, and optionally the snapd map's Components deck.

So a component is an optional part of the snap, tied to its revision, and image-garden has ten of them. Three arrive on their own, the rest you add when you need them. From here, the swtpm deck shows the component that the +tpm systems need, with the Secure Boot firmware. The spread deck shows how spread and spread-plus are chosen. The pkgproxy deck covers the component behind the default proxy, and its alternatives. And if you want to see how snapd itself handles components, the snapd map has a deck on them.

Details and sources

Details

  • The three that arrive on their own, on a snap from the store: the QEMU for the host's architecture, pkgproxy and spread.

Read more

Basis of the statements on this page

Read in the image-garden source at the commit this map describes ("code"): snap/snapcraft.yaml, the hooks in snap/hooks/, qemu-stubs/, spread-chooser/ and the mk/ files that check for components. How snapd installs, mounts, refreshes and lists components, and when it runs each hook, is snapd's behaviour, read in snapd's source and on the snapd map ("derived"). Nothing was run for this page.

The components

ComponentContentsInstalled by
qemu-x86-64qemu-system-x86_64, its BIOS, EDK2 and option ROM files, and the Secure Boot OVMF pair in share/ovmfthe install hook on x86_64 hosts; post-refresh puts it back
qemu-aarch64qemu-system-aarch64, EDK2, efi-virtio.rom, Fedora's and Jammy's EDK2 buildsthe install hook on aarch64 hosts; post-refresh puts it back
qemu-riscv64qemu-system-riscv64, EDK2, OpenSBI, efi-virtio.romyou: snap install image-garden+qemu-riscv64
qemu-s390xqemu-system-s390x, s390-ccw.img, efi-virtio.romyou
qemu-ppc64qemu-system-ppc64, SLOF, VOF and VGA BIOS filesyou
qemu-loongarch64qemu-system-loongarch64, EDK2, efi-virtio.romyou
pkgproxybin/pkgproxy, bin/pkgproxyctlthe install hook; configure when pkgproxy is set back to component; post-refresh
swtpmbin/swtpm and the libraries the base lacks, in lib/swtpmyou: snap install image-garden+swtpm
spreadspreadthe configure hook when spread-variant is empty, so at install; the spread app, run as root, when it is missing
spread-plusspread (spread-plus, renamed)the configure hook with spread-variant=plus; the spread app, run as root, when a spread.yaml asks for it

Sources: snapcraft.yaml:45-119, snapcraft.yaml:378-429, snapcraft.yaml:459-486, snapcraft.yaml:545-665, install:6-14, configure:41-107, post-refresh:9-29, spread-chooser:35-58.

Commands

CommandWhat it does
snap install image-garden+NAMEinstall one component of the installed snap
snap install --dangerous ./image-garden+NAME_*.compinstall a component from its file, for a snap installed from a file
snap components image-gardenlist installed and available components (derived, snapd)
snap remove image-garden+NAMEremove one component (derived, snapd)
snapctl install +NAMEwhat the snap's hooks run, and the spread app when run as root; from a hook the install is queued until the hook ends

Where a component lives

The snap's stubs, hooks and make rules all look in $SNAP/../components/$SNAP_REVISION/NAME, which is /snap/image-garden/components/REVISION/NAME (qemu-system-x86_64:10, post-refresh:12, 010-qemu.mk:50-55). The directory is named after the snap's revision, so each revision sees only its own components.

Messages when a component is missing

WhereMessageSource
make, before a firmware copy (x86_64, aarch64, riscv64, loongarch64)install qemu-aarch64 component to use aarch64 emulation010-qemu.mk:50-55
make, before a +tpm downloadinstall the swtpm component to use systems with a TPM: snap install image-garden+swtpm010-qemu-x86_64.mk:124-131
a QEMU stuba message headed Notice, then snap install image-garden+qemu-<arch>qemu-system-x86_64:9-31
the swtpm stuba message headed Notice, then snap install image-garden+swtpmswtpm:11-32
the pkgproxyctl stuba message headed Notice, then snap install image-garden+pkgproxypkgproxyctl:6-27
the pkgproxy servicepkgproxy: waiting for the pkgproxy component (snap install image-garden+pkgproxy), then waitspkgproxy:11-16
image-garden.spread, its spread component missinga message headed Notice, "The image-garden snap requires the component spread-plus in order to run spread.", then snap install image-garden+spread-plusspread-chooser:11-33
the configure hook, pkgproxy set back to componentcannot install the pkgproxy component: snap install image-garden+pkgproxyconfigure:48-53

for contributors

How the components are built

  • One qemu part builds QEMU once for all six targets; its component shell function installs each target's binary, the keymaps and a named list of firmware files into components/qemu-<arch>, and organize moves those into (component/qemu-<arch>)/. The snap keeps only qemu-img from the build (snapcraft.yaml:327-429).
  • The spread and spread-plus parts build each runner with Go and organize the binary into its component as spread (snapcraft.yaml:545-583).
  • The swtpm and ovmf-x86-64 parts stage Ubuntu packages, keep a few files in component/ and delete the rest (snapcraft.yaml:608-665).

Roads from here

SNAP · snap-only features

Snapd map ↗

  • Components — optional, how snapd itself installs, refreshes and removes components