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

Part of journeys

01 Everything in one install

THE SNAP QEMU × 6 arches firmware a caching proxy collected by hand? $ snap install image-garden image-garden + its make rules QEMU, built with the patch the same source as the container the image-garden tree git tag a stable revision it follows upstream releases
snap install image-garden brings the image-garden command and its make rules, QEMU for six architectures, firmware and pkgproxy; the snap is built from the image-garden tree and a tagged release becomes a stable revision

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 grade stable, any other gets tag+gitN.hash and grade devel (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.

02 What the install adds

THE INSTALL HOOK install hook asks snapd for two components +qemu-<your architecture> PC: qemu-x86-64 Pi: qemu-aarch64 +pkgproxy runs as a service +spread: from the configure hook, right after other QEMUs, swtpm wait until needed a sideloaded snap no components from the hook post-refresh hook puts back a missing QEMU or pkgproxy
The install hook asks snapd for two components: QEMU for the host architecture, qemu-x86-64 on a PC or qemu-aarch64 on a Raspberry Pi, and pkgproxy, which runs as a snap service; everything else waits; sideloaded snaps get nothing from the hook; the post-refresh hook restores missing components

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 runs snapctl install on 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 +pkgproxy when the pkgproxy setting is unset, true or component and the component is missing (post-refresh:9-29).
  • pkgproxy runs as the snap's pkgproxy app, daemon: simple, restart-condition: always (snapcraft.yaml:227-246).

03 The rest, when you need it

ON DEMAND $ image-garden make ubuntu-cloud-24.04.aarch64.run qemu-system-aarch64 stub component? ┌──────────── Notice ────────────┐ Install the component with the following command: snap install image-garden+qemu-aarch64 snap install image-garden+swtpm by hand, for the +tpm systems spread already there: the configure hook adds it
Building an aarch64 system on a PC runs the qemu-system-aarch64 stub, which finds no component and prints a notice with snap install image-garden+qemu-aarch64; swtpm is installed the same way; spread is already there, added by the configure hook at install

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 in snap 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 +spread when spread-variant is 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, the spread app installs it only when run as root; otherwise it stops with a message ending in snap install image-garden+COMPONENT, such as image-garden+spread-plus (spread-chooser:35-49). The README says the configure hook installs spread at install (README.md:163-169).

Read more

04 Strict confinement, briefly

STRICT CONFINEMENT image-garden and its QEMU kvm home network keep projects under your home /var/tmp → TMPDIR=~/snap/image-garden/common/tmp no login session → /run/snap.image-garden pkgproxy snap pkgproxy-sockets a content interface
The confined image-garden and QEMU reach KVM, the home directory and the network through interfaces; temporary files move from /var/tmp to ~/snap/image-garden/common/tmp, on disk; without a login session pid files go to /run/snap.image-garden; a separate pkgproxy snap connects through the pkgproxy-sockets content interface

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-garden app plugs kvm, home, network, network-bind and pkgproxy-sockets (snapcraft.yaml:122-131).
  • Every QEMU app and image-garden itself run through qemu-var-tmp. When /var/tmp is not writable, as under strict confinement, it sets TMPDIR=$SNAP_USER_COMMON/tmp, that is ~/snap/image-garden/common/tmp, and only if that cannot be made TMPDIR=/tmp/./, the snap's private /tmp (qemu-var-tmp:9-23). QEMU keeps the -snapshot overlay there; the README says why: the snap's /tmp "is a tmpfs on many hosts" (README.md:155-161).
  • When snapd's XDG_RUNTIME_DIR and its parent do not exist, as for root without a login session, image-garden uses /run/snap.$SNAP_INSTANCE_NAME for pid files (image-garden:66-73).
  • The pkgproxy-sockets content 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 needs snap connect image-garden:pkgproxy-sockets pkgproxy:sockets (snapcraft.yaml:255-266).
  • The virtiofsd app plugs only home and network-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.

05 Where your images live

WHERE IMAGES LIVE outside a snap ~/.cache/image-garden/dl/ in the snap ~/snap/image-garden/common/cache/dl/ survives refreshes prepared disks and launchers your-project/.image-garden/ubuntu-cloud-24.04.x86_64.run pkgproxy's cache, for every user /var/snap/image-garden/common/cache/pkgproxy/
Outside a snap downloads go to ~/.cache/image-garden/dl; in the snap to ~/snap/image-garden/common/cache/dl, which survives refreshes; prepared disks and launchers stay in the project or .image-garden; pkgproxy's cache is in /var/snap/image-garden/common/cache/pkgproxy, shared by all users

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_DIR defaults to $SNAP_USER_COMMON/cache; elsewhere to $XDG_CACHE_HOME/image-garden. GARDEN_DL_DIR defaults to $GARDEN_CACHE_DIR/dl (image-garden:20-29, 000-garden.mk:9-12).
  • $SNAP_USER_COMMON is ~/snap/image-garden/common and $SNAP_COMMON is /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 make runs in .image-garden/ when that directory exists, otherwise in the current directory (image-garden:982-993).

06 Where to go from here

ROADS The snap image-garden make build your first system Components qemu-*, swtpm, spread pkgproxy= setting which proxy guests use spread-variant spread or spread-plus swtpm in the snap Confinement what strict changes Three ways in snap, container, packages
Seven roads from the snap deck: image-garden make, components, the pkgproxy setting, spread-variant, swtpm, confinement and the comparison of three installs

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, then image-garden make ubuntu-cloud-24.04.x86_64.run, then ./ubuntu-cloud-24.04.x86_64.run.

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

CommandWhat it runs
image-gardenthe image-garden script (snapcraft.yaml:122-131)
image-garden.qemu-system-x86-64, -aarch64, -riscv64, -s390x, -ppc64, -loongarch64QEMU from the matching component; the app names use - where the binary has _ (snapcraft.yaml:149-210)
image-garden.spreadspread or spread-plus, picked by spread-chooser (snapcraft.yaml:211-226)
image-garden.swtpmswtpm from its component, for TPM launchers run outside the snap (snapcraft.yaml:132-139)
image-garden.virtiofsdthe bundled virtiofsd, through a stub that adds --sandbox none; plugs home and network-bind (snapcraft.yaml:140-148, virtiofsd:6-15)
image-garden.pkgproxythe bundled pkgproxy, a service (snapcraft.yaml:227-246)
image-garden.pkgproxyctlpkgproxy's control tool, for example image-garden.pkgproxyctl stats (snapcraft.yaml:247-249, README.md:207-209)

Components

ComponentContentsInstalled
qemu-x86-64QEMU for x86_64, with its firmware and the Secure Boot OVMFby the install hook on x86_64 hosts
qemu-aarch64QEMU for aarch64, with EDK2by the install hook on aarch64 hosts
qemu-riscv64, qemu-s390x, qemu-ppc64, qemu-loongarch64QEMU for that architectureby hand: snap install image-garden+qemu-riscv64
pkgproxypkgproxy and pkgproxyctlby the install hook
swtpmthe TPM emulator for the +tpm systemsby hand: snap install image-garden+swtpm
spreadspreadby the configure hook at install, while spread-variant is empty
spread-plusspread-plussnap 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

SettingValuesEffect
pkgproxyunset, true, componentthe bundled pkgproxy service (default)
pkgproxynone, falseno pkgproxy; the service is stopped
pkgproxysnapthe pkgproxy snap on this host, through pkgproxy-sockets
pkgproxyhttp://host[:port]a pkgproxy elsewhere
spread-variantemptythe spread component
spread-variantplus: lowercase letters, digits and single dashes, starting with a letter, not ending with a dashthe 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

PathWhat
~/snap/image-garden/common/cache/dldownloaded images ($SNAP_USER_COMMON/cache/dl)
~/snap/image-garden/common/tmpQEMU's scratch, the -snapshot overlays of running machines ($SNAP_USER_COMMON/tmp, qemu-var-tmp:9-20)
/var/snap/image-garden/common/cache/pkgproxythe bundled pkgproxy's cache
/var/snap/image-garden/common/pkgproxy.sockthe bundled pkgproxy's socket, which guests reach through QEMU

Roads from here

START HERE

RUNTIME · make rules and the CLI

SNAP · snap-only features