The image-garden snap
strict, core26 for users for CI operators
Installing image-garden as a snap. Its hooks add QEMU for the host architecture, pkgproxy and spread as components, everything else is installed on demand, strict confinement adjusts a few paths, and images live in the snap's own cache directory. The snap is built from the image-garden tree and follows its releases.
On the map: snap
▶ Watch this deck — 6 scenes, ~4 min
Worth seeing first
- Snap, container or native package — how the snap compares with the container and native packages
Part of journeys
- Your first garden VM, step 1 of 4 · next: image-garden make and the other commands
01 Everything in one install
snap install image-garden gives you image-garden, its make rules and a patched QEMU. The snap is built from the image-garden tree and follows its releases.
Say you want image-garden, but you'd rather not collect QEMU for six architectures, the right firmware and a caching proxy by hand. The snap brings all of that. One command, snap install image-garden, and you have the image-garden command with the same make rules as every other install, plus a QEMU built from the same patched source as the container. The snap is built from the image-garden tree itself, and a tagged release becomes a stable revision, so it follows upstream closely. This deck shows what the install adds, what confinement changes, and where your images end up.
Details and sources
Details
- The snap is
name: image-garden,base: core26,confinement: strict(snapcraft.yaml:3, snapcraft.yaml:5, snapcraft.yaml:43). Its description lists what it bundles: image-garden, spread and spread-plus, QEMU for six architectures, swtpm, Secure Boot OVMF, pkgproxy, virtiofsd, make, curl, tar, xorriso and coreutils (snapcraft.yaml:6-41). - The version comes from
git describe --tags: a revision built exactly at a tag gets that tag as its version and gradestable, any other getstag+gitN.hashand gradedevel(snapcraft.yaml:278-301). - The install command is
snap install image-garden(README.md:132-137). - The snap's QEMU and the container's QEMU both carry
qemu-patches/guestfwd-unix-socket.patch; see the guestfwd patch.
Read more
02 What the install adds
The install hook installs +qemu-your architecture and +pkgproxy; the configure hook then adds +spread. The post-refresh hook puts them back if they are missing. Sideloaded snaps get no components from the hooks.
Installing the snap runs its install hook, and the hook asks snapd for two components straight away. The first is QEMU for your own machine's architecture: on a PC that's qemu-x86-64, on a Raspberry Pi it's qemu-aarch64. The second is pkgproxy, the caching proxy that guests use by default, which runs as a service of the snap. Right after that, the configure hook adds spread. Everything else waits until you need it. A snap you sideload yourself gets nothing from the hook, so there you install components by hand. And after every refresh, another hook checks that your QEMU and pkgproxy are still in place.
Details and sources
Details
- The install hook builds the list
+qemu-$(uname -m)(with_turned into-) and+pkgproxy, and runssnapctl installon it, unless the revision is a sideloaded one (x1,x2, …) (install:6-14). - The post-refresh hook adds the host's QEMU component when it is missing, and
+pkgproxywhen thepkgproxysetting is unset,trueorcomponentand the component is missing (post-refresh:9-29). - pkgproxy runs as the snap's
pkgproxyapp,daemon: simple,restart-condition: always(snapcraft.yaml:227-246).
Read more
03 The rest, when you need it
A missing QEMU component stops the stub, which shows a message naming snap install image-garden+qemu-aarch64. swtpm is installed the same way; spread is added by the configure hook at install.
So what happens when you need something that isn't installed yet? Say you build an Arm system on a PC. Make runs QEMU for that architecture, and in the snap that command is a small stub. It looks for the component, and when it's missing it stops and shows a message with the exact command to run: snap install image-garden+qemu-aarch64. swtpm, which only the Ubuntu Core +tpm systems need, comes the same way, by hand. spread is usually there already: the configure hook adds it at install, and spread-plus comes when you choose that variant.
Details and sources
Details
- Each
qemu-system-*command in the snap is a stub that runs the binary from$SNAP/../components/$SNAP_REVISION/qemu-<arch>/bin/, or prints a notice ending insnap install image-garden+qemu-<arch>and exits 1 (qemu-system-x86_64:6-36). The aarch64 stub is the same with its own names. - swtpm is in its own component and is not installed automatically:
snap install image-garden+swtpm(README.md:326-334). - The configure hook runs
snapctl install +spreadwhenspread-variantis empty and spread is missing, or+spread-<variant>for a variant (configure:83-107); snapd runs that hook at install, so a store install has spread at once. When a project asks for a spread component that is missing, thespreadapp installs it only when run as root; otherwise it stops with a message ending insnap install image-garden+COMPONENT, such asimage-garden+spread-plus(spread-chooser:35-49). The README says the configure hook installs spread at install (README.md:163-169).
Read more
- Snap components, swtpm in the snap, choosing a spread.
- Optional, for the feature in general: the snapd map's Components deck.
04 Strict confinement, briefly
Plugs: kvm, home, network, network-bind, pkgproxy-sockets. Keep projects under your home directory. QEMU's temporary files go to ~/snap/image-garden/common/tmp, and pid files are redirected for you.
The snap is strictly confined, and you'll notice it in a few places. image-garden and its QEMU get KVM, your home directory and the network through snap interfaces, and little else, so keep your projects under your home directory. A few things are adjusted for you. QEMU puts large temporary files in /var/tmp, which the snap may not use, so a small wrapper sends them to the snap's directory in your home, on disk. Without a login session, as under sudo, pid files go to the snap's own place in /run. And a separate pkgproxy snap reaches this one through a content interface.
Details and sources
Details
- The
image-gardenapp plugskvm,home,network,network-bindandpkgproxy-sockets(snapcraft.yaml:122-131). - Every QEMU app and image-garden itself run through
qemu-var-tmp. When/var/tmpis not writable, as under strict confinement, it setsTMPDIR=$SNAP_USER_COMMON/tmp, that is~/snap/image-garden/common/tmp, and only if that cannot be madeTMPDIR=/tmp/./, the snap's private/tmp(qemu-var-tmp:9-23). QEMU keeps the-snapshotoverlay there; the README says why: the snap's/tmp"is a tmpfs on many hosts" (README.md:155-161). - When snapd's
XDG_RUNTIME_DIRand its parent do not exist, as for root without a login session, image-garden uses/run/snap.$SNAP_INSTANCE_NAMEfor pid files (image-garden:66-73). - The
pkgproxy-socketscontent plug mounts a pkgproxy snap's sockets at$SNAP_COMMON/pkgproxy-host-snap; snapd connects it automatically when both snaps come from the store, a sideloaded snap needssnap connect image-garden:pkgproxy-sockets pkgproxy:sockets(snapcraft.yaml:255-266). - The
virtiofsdapp plugs onlyhomeandnetwork-bind, and its stub runs virtiofsd with--sandbox none, since its own namespace sandbox is not allowed under confinement (snapcraft.yaml:140-148, virtiofsd:6-15). - The home interface is snapd's; which paths it allows is decided there, not in image-garden.
Read more
05 Where your images live
Downloads: ~/snap/image-garden/common/cache/dl. Prepared images: your project or .image-garden/. pkgproxy: /var/snap/image-garden/common/cache/pkgproxy.
Where do the downloads go? Outside a snap, image-garden keeps them in your cache directory. In the snap, the cache moves to the snap's own directory in your home, ~/snap/image-garden/common/cache, with the downloads under dl. That directory isn't tied to a snap revision, so images survive refreshes and are downloaded once. Prepared disks and launchers still land in your project, or in its .image-garden directory. pkgproxy keeps its own cache elsewhere, in the snap's system-wide directory, shared by every user on the machine.
Details and sources
Details
- In the snap,
GARDEN_CACHE_DIRdefaults to$SNAP_USER_COMMON/cache; elsewhere to$XDG_CACHE_HOME/image-garden.GARDEN_DL_DIRdefaults to$GARDEN_CACHE_DIR/dl(image-garden:20-29, 000-garden.mk:9-12). $SNAP_USER_COMMONis~/snap/image-garden/commonand$SNAP_COMMONis/var/snap/image-garden/common; snapd keeps both across revisions (snapd's layout, not image-garden code).- The bundled pkgproxy runs with
-cache-dir $SNAP_COMMON/cache/pkgproxy(snapcraft.yaml:241). image-garden makeruns in.image-garden/when that directory exists, otherwise in the current directory (image-garden:982-993).
Read more
06 Where to go from here
Next: image-garden make, the components, the pkgproxy setting, spread, swtpm, confinement, and the comparison of the three installs.
That's the snap: one install, QEMU for your machine and pkgproxy straight away, everything else on demand, and a cache that survives refreshes. Next, build your first system with image-garden make. If you need another architecture, a TPM system or spread, the components deck lists every one. The pkgproxy setting chooses which proxy guests use, or none. There's a deck on spread and spread-plus, one on swtpm, and one on what strict confinement changes in detail. And if you're still choosing how to install, compare the snap with the container and native packages.
Details and sources
Details
- The first-steps path:
snap install image-garden, thenimage-garden make ubuntu-cloud-24.04.x86_64.run, then./ubuntu-cloud-24.04.x86_64.run.
Read more
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/ and spread-chooser/. The snapd paths are snapd's documented layout ("derived"). Nothing was run for this page.
Apps
| Command | What it runs |
|---|---|
image-garden | the image-garden script (snapcraft.yaml:122-131) |
image-garden.qemu-system-x86-64, -aarch64, -riscv64, -s390x, -ppc64, -loongarch64 | QEMU from the matching component; the app names use - where the binary has _ (snapcraft.yaml:149-210) |
image-garden.spread | spread or spread-plus, picked by spread-chooser (snapcraft.yaml:211-226) |
image-garden.swtpm | swtpm from its component, for TPM launchers run outside the snap (snapcraft.yaml:132-139) |
image-garden.virtiofsd | the bundled virtiofsd, through a stub that adds --sandbox none; plugs home and network-bind (snapcraft.yaml:140-148, virtiofsd:6-15) |
image-garden.pkgproxy | the bundled pkgproxy, a service (snapcraft.yaml:227-246) |
image-garden.pkgproxyctl | pkgproxy's control tool, for example image-garden.pkgproxyctl stats (snapcraft.yaml:247-249, README.md:207-209) |
Components
| Component | Contents | Installed |
|---|---|---|
qemu-x86-64 | QEMU for x86_64, with its firmware and the Secure Boot OVMF | by the install hook on x86_64 hosts |
qemu-aarch64 | QEMU for aarch64, with EDK2 | by the install hook on aarch64 hosts |
qemu-riscv64, qemu-s390x, qemu-ppc64, qemu-loongarch64 | QEMU for that architecture | by hand: snap install image-garden+qemu-riscv64 |
pkgproxy | pkgproxy and pkgproxyctl | by the install hook |
swtpm | the TPM emulator for the +tpm systems | by hand: snap install image-garden+swtpm |
spread | spread | by the configure hook at install, while spread-variant is empty |
spread-plus | spread-plus | snap set image-garden spread-variant=plus; image-garden.spread run as root installs a missing one a project asks for |
Components are declared in snapcraft.yaml:45-119; the install hook is install:6-14.
Settings
| Setting | Values | Effect |
|---|---|---|
pkgproxy | unset, true, component | the bundled pkgproxy service (default) |
pkgproxy | none, false | no pkgproxy; the service is stopped |
pkgproxy | snap | the pkgproxy snap on this host, through pkgproxy-sockets |
pkgproxy | http://host[:port] | a pkgproxy elsewhere |
spread-variant | empty | the spread component |
spread-variant | plus: lowercase letters, digits and single dashes, starting with a letter, not ending with a dash | the spread-<variant> component |
Set them with snap set image-garden pkgproxy=… and snap set image-garden spread-variant=… (configure:11-30, configure:83-107, README.md:163-187, README.md:217-220). A # spread-variant= comment in a project's spread.yaml wins over the setting (spread-chooser:5-9, spread-chooser:51-58).
Paths
| Path | What |
|---|---|
~/snap/image-garden/common/cache/dl | downloaded images ($SNAP_USER_COMMON/cache/dl) |
~/snap/image-garden/common/tmp | QEMU's scratch, the -snapshot overlays of running machines ($SNAP_USER_COMMON/tmp, qemu-var-tmp:9-20) |
/var/snap/image-garden/common/cache/pkgproxy | the bundled pkgproxy's cache |
/var/snap/image-garden/common/pkgproxy.sock | the bundled pkgproxy's socket, which guests reach through QEMU |
Roads from here
START HERE
- Snap, container or native package — the snap, the container and native packages side by side
RUNTIME · make rules and the CLI
- image-garden make and the other commands — build and boot your first system with image-garden make
SNAP · snap-only features
- Snap components — every component and how to add the ones you need
- The pkgproxy snap setting — choose the pkgproxy guests use, or none
- Choosing a spread — run spread or spread-plus from the snap
- swtpm and Secure Boot firmware in the snap — the TPM emulator for the Ubuntu Core +tpm systems
- Living with strict confinement — what strict confinement changes, in detail