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
- The image-garden snap — what the snap is and what its install adds
01 One snap, optional parts
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, sixqemu-<arch>,pkgproxyandswtpm(snapcraft.yaml:45-119). - The README's section on them: "Install only the CPU architectures you need", with
snap install image-garden+qemu-aarch64as 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
- Optional, for the feature in general: the snapd map's Components deck.
- The snap, what the install adds.
02 How a component behaves
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 insnapcraft.yaml; snapcraft'sorganizeputs 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 componentslists the installed and available components of installed snaps;snap remove image-garden+swtpmremoves one;snapctl installaccepts+comporsnap+compfor the calling snap only. The revision R on the slide stands for any revision number.
Read more
- Optional: the snapd map's Components, snapctl and hook lifecycle decks.
03 image-garden's ten components
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
- The components and their summaries (snapcraft.yaml:45-119). spread and spread-plus are pinned to Git revisions; each QEMU component has the version of the bundled QEMU; pkgproxy has its own version; swtpm takes the version of the Ubuntu package staged (snapcraft.yaml:117-119, snapcraft.yaml:621-632).
- One QEMU build serves all six QEMU components: a shell function puts
qemu-system-<arch>, the keymaps and the firmware files that architecture's machines load into each one; the snap itself keeps onlyqemu-img(snapcraft.yaml:327-429). - The Secure Boot OVMF pair goes into
qemu-x86-64(snapcraft.yaml:645-665); Fedora's and Jammy's EDK2 builds for some aarch64 systems go intoqemu-aarch64(snapcraft.yaml:459-486). - pkgproxy's component holds
bin/pkgproxyandbin/pkgproxyctl(snapcraft.yaml:599-601); swtpm's holdsbin/swtpmand its libraries (snapcraft.yaml:608-644). - The stubs installed into the snap: the six
qemu-system-*,pkgproxy,pkgproxyctl,swtpmandvirtiofsd(qemu-stubs/Makefile:10); spread's stand-in isspread-chooser(snapcraft.yaml:211-226). All butvirtiofsdstand in for a program in a component. - virtiofsd is not a component: the snap itself stages
usr/libexec/virtiofsdfrom Ubuntu'svirtiofsdpackage (snapcraft.yaml:602-607), and theimage-garden.virtiofsdapp runs it through its stub, which adds--sandbox none(snapcraft.yaml:140-148, virtiofsd:6-15).
Read more
- The full table is in this deck's reference and in the snap's.
- Firmware per system, swtpm in the snap, choosing a spread.
04 Which arrive on their own
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-variantempty it installs+spreadwhencomponents/REVISION/spread/spreadis missing; with a variant,+spread-VARIANT(configure:83-107). Withpkgproxyset (not unset) tocomponentortrueand the component missing, it installs+pkgproxy(configure:41-55). - post-refresh: the host's QEMU component if its directory is missing, and
+pkgproxywhenpkgproxyis unset,trueorcomponentand 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 installrun from a hook (derived,overlord/hookstate/ctlcmd/helpers.goin 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 thespread-variantsetting 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.
Read more
- What the install adds, choosing a spread, the pkgproxy setting.
- Optional: the snapd map's hook lifecycle.
05 When a component is missing
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 insnap 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 componentand checks every 5 seconds, so thatrestart-condition: alwaysdoes not crash-loop (qemu-stubs/pkgproxy:6-18).
Read more
06 A snap from a file gets none
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 installwhen$SNAP_REVISIONmatchesx[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 withsnap install --dangerous ./image-garden+pkgproxy_*.comp" (README.md:228-232). - Derived, from snapd: a revision installed from a file gets a local revision,
x1,x2and 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 installonly as root, which on a sideloaded snap has nothing to fetch either; then it stops with a message and thesnap install image-garden+COMPONENTcommand (spread-chooser:35-49). For a sideloaded snap, install the component's.compfile instead.
Read more
- Reaching out of the sandbox, the pkgproxy setting (a sideloaded snap also needs
snap connectforpkgproxy=snap).
07 Where to go from here
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
- swtpm in the snap, choosing a spread, the pkgproxy setting, the snap, confinement.
- Optional: the snapd map's Components deck.
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
| Component | Contents | Installed by |
|---|---|---|
qemu-x86-64 | qemu-system-x86_64, its BIOS, EDK2 and option ROM files, and the Secure Boot OVMF pair in share/ovmf | the install hook on x86_64 hosts; post-refresh puts it back |
qemu-aarch64 | qemu-system-aarch64, EDK2, efi-virtio.rom, Fedora's and Jammy's EDK2 builds | the install hook on aarch64 hosts; post-refresh puts it back |
qemu-riscv64 | qemu-system-riscv64, EDK2, OpenSBI, efi-virtio.rom | you: snap install image-garden+qemu-riscv64 |
qemu-s390x | qemu-system-s390x, s390-ccw.img, efi-virtio.rom | you |
qemu-ppc64 | qemu-system-ppc64, SLOF, VOF and VGA BIOS files | you |
qemu-loongarch64 | qemu-system-loongarch64, EDK2, efi-virtio.rom | you |
pkgproxy | bin/pkgproxy, bin/pkgproxyctl | the install hook; configure when pkgproxy is set back to component; post-refresh |
swtpm | bin/swtpm and the libraries the base lacks, in lib/swtpm | you: snap install image-garden+swtpm |
spread | spread | the configure hook when spread-variant is empty, so at install; the spread app, run as root, when it is missing |
spread-plus | spread (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
| Command | What it does |
|---|---|
snap install image-garden+NAME | install one component of the installed snap |
snap install --dangerous ./image-garden+NAME_*.comp | install a component from its file, for a snap installed from a file |
snap components image-garden | list installed and available components (derived, snapd) |
snap remove image-garden+NAME | remove one component (derived, snapd) |
snapctl install +NAME | what 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
| Where | Message | Source |
|---|---|---|
| make, before a firmware copy (x86_64, aarch64, riscv64, loongarch64) | install qemu-aarch64 component to use aarch64 emulation | 010-qemu.mk:50-55 |
| make, before a +tpm download | install the swtpm component to use systems with a TPM: snap install image-garden+swtpm | 010-qemu-x86_64.mk:124-131 |
| a QEMU stub | a message headed Notice, then snap install image-garden+qemu-<arch> | qemu-system-x86_64:9-31 |
| the swtpm stub | a message headed Notice, then snap install image-garden+swtpm | swtpm:11-32 |
| the pkgproxyctl stub | a message headed Notice, then snap install image-garden+pkgproxy | pkgproxyctl:6-27 |
| the pkgproxy service | pkgproxy: waiting for the pkgproxy component (snap install image-garden+pkgproxy), then waits | pkgproxy:11-16 |
image-garden.spread, its spread component missing | a message headed Notice, "The image-garden snap requires the component spread-plus in order to run spread.", then snap install image-garden+spread-plus | spread-chooser:11-33 |
| the configure hook, pkgproxy set back to component | cannot install the pkgproxy component: snap install image-garden+pkgproxy | configure:48-53 |
for contributors
How the components are built
- One
qemupart builds QEMU once for all six targets; itscomponentshell function installs each target's binary, the keymaps and a named list of firmware files intocomponents/qemu-<arch>, andorganizemoves those into(component/qemu-<arch>)/. The snap keeps onlyqemu-imgfrom the build (snapcraft.yaml:327-429). - The
spreadandspread-plusparts build each runner with Go and organize the binary into its component asspread(snapcraft.yaml:545-583). - The
swtpmandovmf-x86-64parts stage Ubuntu packages, keep a few files incomponent/and delete the rest (snapcraft.yaml:608-665).
Roads from here
SNAP · snap-only features
- swtpm and Secure Boot firmware in the snap — the swtpm component and the Secure Boot firmware for the +tpm systems
- Choosing a spread — the spread and spread-plus components, and which one runs
- The pkgproxy snap setting — the pkgproxy component and the other pkgproxy choices
- The image-garden snap — the rest of the snap, its paths and its cache
- Living with strict confinement — what else changes when the snap is confined or sideloaded
Snapd map ↗
- Components — optional, how snapd itself installs, refreshes and removes components