How image-garden turns a few lines of .ini into a running test VM for thirteen distributions and six architectures: the data and rules behind it, what cloud-init changes in each system, the make targets you run, pkgproxy's part, and the snap, container and source builds, one narrated deck per topic. Pick any place, follow the roads at the end of each deck, and switch perspective at the top to see only what applies to you. The caching proxy has its own map: the pkgproxy map.
Source: gitlab.com/zygoon/image-garden-map · report a problem or suggest a change
Click a place to enter it. Inside a topic you see only its exits; m brings the whole map back. space plays, ← → step. This map describes image-garden at release v0.8.1 (commit a5785d52). Where it says "the snap" or "the container", it means the ones built from that tree.
Arm guests are emulated on a PC and run under KVM on an Arm host, which the README ranks tier 2. ubuntu-cloud-24.04.aarch64 uses the arm64 image from the same SHA256SUMS as the x86_64 example.
ubuntu-cloud-24.04.aarch64 downloads noble-server-cloudimg-arm64.img and checks it against https://cloud-images.ubuntu.com/noble/current/SHA256SUMS, the list the x86\_64 example uses. Distributions name the architecture arm64 or aarch64; image-garden's system names always say aarch64.-accel help, the vCPU rule) is in six architectures.[ubuntu-cloud-24.04.aarch64] (data/ubuntu.ini:244-249), beside the x86\_64 one (:237-242). map_to_debian_arch turns aarch64 into arm64 where a download name needs it (mk/000-garden.mk:27-30).qemu-system-aarch64 -machine virt,gic-version=max -cpu max, -cpu neoverse-n1 for Amazon Linux; -smp 1 under TCG on a PC, -smp 4 on an aarch64 host; -m 2048.
virt,gic-version=max, CPU max, 1 vCPU unless the host is aarch64, then 4; memory 2048 MiB; network virtio-net-pci with -smbios type=41, as on x86\_64.-cpu neoverse-n1; the change "fixes booting for both … It requires sufficiently new ARM CPU if used natively on the same architecture" (commit 3477e1a).virt, gic-version=max and max mean is QEMU's documentation (derived): gic-version=max picks the highest GIC version the accelerator offers, which under KVM depends on the host's interrupt controller. That interrupt controllers differ across Arm hardware is noted in image-garden's CI (.gitlab-ci.yml:635-643).QEMU_SYSTEM_AARCH64, QEMU_SYSTEM_AARCH64_MACHINE = virt,gic-version=max, QEMU_CPU_AARCH64 = max, QEMU_SMP_AARCH64 = 1 and the network option (mk/010-qemu-aarch64.mk:3-10); the target-specific QEMU_CPU_AARCH64=neoverse-n1 (mk/050-amazonlinux-2.mk:10-11); the native count and memory (mk/010-qemu.mk:5-12).Most aarch64 systems boot the host's EDK2; ten older ones boot Fedora's build and Ubuntu 14.04 and 16.04 Ubuntu's from 22.04, both in the snap's component or downloaded by checksum.
/usr/share/AAVMF/AAVMF_CODE.fd (Debian and Ubuntu's qemu-efi-aarch64, derived from the package) and /usr/share/qemu/aavmf-aarch64-code.bin, then in the snap's component, then under $GARDEN_AARCH64_PREFIX/share/qemu/.almalinux-cloud-8, amazonlinux-cloud-2, amazonlinux-cloud-2023, fedora-cloud-38, opensuse-cloud-15.4, opensuse-cloud-15.5, oracle-cloud-8, rocky-cloud-8, ubuntu-core-22 and ubuntu-core-22+dangerous; Ubuntu's 2022.02 build by ubuntu-cloud-14.04 and ubuntu-cloud-16.04, whose 4.4 kernel stops with "Failed to update FDT and exit boot services" under Fedora's.46 cloud systems from 12 families and 6 Ubuntu Core systems, all efi. Not on aarch64: archlinux-cloud, oracle-cloud-7, the end-of-life Ubuntu interims, ubuntu-core-16, -18, -20 and the +tpm systems.
almalinux-cloud-8, -9, -10; alpine-cloud-3; amazonlinux-cloud-2, -2023; centos-cloud-9, -10; debian-cloud-10 to -14 and -sid; fedora-cloud-38 to -45; gentoo-cloud; opencloudos-cloud-9; opensuse-cloud-15.4, -15.5, -15.6, -16.0, -16.1, -tumbleweed; oracle-cloud-8, -9, -10; rocky-cloud-8, -9, -10; ubuntu-cloud-14.04, 16.04, 18.04, 20.04, 22.04, 24.04, 25.04, 25.10, 26.04, 26.10 (counted at the pinned commit).data/*.ini; Ubuntu Core's aarch64 systems leave out 16, 18 and 20, "no aarch64 image", and the +tpm check is at mk/050-ubuntu-core.mk:4-21.Snap: snap install image-garden+qemu-aarch64, automatic on aarch64 hosts. Container: images for x86_64 and aarch64 hosts. Ubuntu: qemu-system-arm and qemu-efi-aarch64.
qemu-aarch64 itself on an aarch64 host, at install and refresh; a snap installed from a file installs no component (snap/hooks/install:6-13). The component holds qemu-system-aarch64, edk2-aarch64-code.fd, edk2-arm-vars.fd, efi-virtio.rom and the edk2-fedora/ and edk2-jammy/ builds (snap/snapcraft.yaml:67-73, :402-403).snap install image-garden+qemu-aarch64 (qemu-stubs/qemu-system-aarch64:9-31).--device /dev/kvm to use KVM.qemu-system-arm (which has qemu-system-aarch64) and qemu-efi-aarch64. Distribution packages may be older than the upstream release (the maintainer's statement).docker-arch, .gitlab-ci.yml:1238-1259).mk/010-qemu-aarch64.mk sets QEMU_CPU_AARCH64 = max, overridden per target in mk/050-amazonlinux-2.mk, and the lists GARDEN_AARCH64_FEDORA_EDK2_SYSTEMS and GARDEN_AARCH64_JAMMY_EDK2_SYSTEMS. The aarch64 CI stage has allow_failure: true.
QEMU_CPU_X86_64 ?= max, QEMU_CPU_AARCH64 = max is a plain assignment, so the environment cannot change it; the command line and target-specific assignments can (mk/050-amazonlinux-2.mk:10-11).GARDEN_AARCH64_FEDORA_EDK2_SYSTEMS and GARDEN_AARCH64_JAMMY_EDK2_SYSTEMS (?=) and the pinned EDK2_AARCH64_FEDORA, EDK2_AARCH64_JAMMY and their checksums, which "snap/snapcraft.yaml and that job read" (mk/010-qemu-aarch64.mk:114-213, snap/snapcraft.yaml:431-460).BOOT_BY_ARCH: aarch64 takes efi only (rulegen.py:302-309); Ubuntu Core's aarch64 rules (mk/050-ubuntu-core.mk:30-53)..systems-aarch64 runs on runners tagged aarch64, kvm, with allow_failure: true; its comment names the reasons: interrupt controller and page size differ across hardware and images, much hardware lacks nested virtualisation, and some images are untested (.gitlab-ci.yml:635-661). Amazon Linux runs in "aarch64: [el-emulated]" on x86\_64 (.gitlab-ci.yml:907-917), because Neoverse N1 needs "more recent ARM instruction set than is supported on Raspberry Pi 5" (commit 422add9).Arm hosts vary in GIC, page size and nested virtualisation. On a Raspberry Pi 5, run Amazon Linux with QEMU_ACCEL_MACHINE_PROP=,accel=tcg. +tpm on aarch64 stops make: ubuntu-core with +tpm is only available for x86_64.
/dev/kvm inside a cloud VM is general knowledge (derived).neoverse-n1 CPU needs a newer Arm core than a Raspberry Pi 5 has (commits 3477e1a and 422add9); QEMU_ACCEL_MACHINE_PROP=,accel=tcg makes a .run script use TCG (mk/010-qemu-aarch64.mk:34). What KVM does with that CPU model on an older core was not run (derived).Next: UEFI firmware per system, six architectures, the support matrix, Ubuntu Core, snap components, the container in CI and x86_64.
Read in the README, mk/010-qemu-aarch64.mk, mk/010-qemu.mk, mk/050-amazonlinux-2.mk, mk/050-ubuntu-core.mk, rulegen.py, data/*.ini, snap/snapcraft.yaml, snap/hooks/install, qemu-stubs/qemu-system-aarch64, the Dockerfile, .gitlab-ci.yml and the commit messages of 3477e1a and 422add9 of image-garden, at the commit in garden.commit ("code"). The system counts were taken from the INI files at that commit. What virt, gic-version=max and the CPU models do inside QEMU and KVM, Debian's package paths, and byte order are derived. Nothing was run for this page.
| Fact | Value |
|---|---|
| QEMU program | qemu-system-aarch64; in the snap the image-garden.qemu-system-aarch64 app |
| Machine | virt,gic-version=max |
| CPU | max; neoverse-n1 for amazonlinux-cloud-2 and -2023 |
| Accelerator | kvm:tcg when QEMU lists KVM (an aarch64 host), else tcg |
| vCPUs | 4 on an aarch64 host, 1 elsewhere |
| Memory | -m 2048 |
| Boot types | efi only |
| Firmware | the host's EDK2 (AAVMF_CODE.fd, AAVMF_VARS.fd), copied to efi-code.aarch64.img and efi-vars.aarch64.img; Fedora's QEMU_EFI-pflash.qcow2 and vars-template-pflash.qcow2 for ten systems; Ubuntu's 2022.02 AAVMF_CODE.fd and AAVMF_VARS.fd for two |
| Network | -netdev user, virtio-net-pci, -smbios type=41 |
| Snap component | qemu-aarch64, installed by the snap on aarch64 hosts; snap install image-garden+qemu-aarch64 elsewhere |
| Container | images for x86\_64 and aarch64 hosts |
| Ubuntu packages | qemu-system-arm, qemu-efi-aarch64 |
| Host tier | 2: feature preview, tested on Raspberry Pi |
| Byte order | little-endian (derived) |
| Firmware | Systems |
|---|---|
| Fedora's EDK2 | almalinux-cloud-8, amazonlinux-cloud-2, amazonlinux-cloud-2023, fedora-cloud-38, opensuse-cloud-15.4, opensuse-cloud-15.5, oracle-cloud-8, rocky-cloud-8, ubuntu-core-22, ubuntu-core-22+dangerous |
| Ubuntu's EDK2 2022.02 | ubuntu-cloud-14.04, ubuntu-cloud-16.04 |
| the host's EDK2 | the other 36 cloud systems and ubuntu-core-24, -26, -24+dangerous, -26+dangerous |
Not on aarch64: archlinux-cloud, oracle-cloud-7, the end-of-life Ubuntu interims 16.10 to 24.10, ubuntu-core-16, -18, -20, and every +tpm system.
| Variable | Effect |
|---|---|
QEMU_ACCEL_MACHINE_PROP | ,accel=tcg forces emulation, for Amazon Linux on a Raspberry Pi 5 |
QEMU_SMP_OPTION, QEMU_MEM_OPTION | replace -smp N and -m 2048 |
QEMU_BOOT_FIRMWARE_OPTION | replaces the two pflash drives |
| Fact | Source |
|---|---|
| Program, machine, CPU, SMP, network | mk/010-qemu-aarch64.mk:3-10 |
| Amazon Linux CPU | mk/050-amazonlinux-2.mk:10-11 |
| Native vCPU count, memory | mk/010-qemu.mk:5-12 |
| Efi only | rulegen.py:302-309 |
| Firmware lists, copies, older builds | mk/010-qemu-aarch64.mk:76-213 |
| Snap component | snap/snapcraft.yaml:67-73, :402-403, :431-460 |
| CI | .gitlab-ci.yml:635-661, :841-917 |
| Make variable | Effect |
|---|---|
QEMU_CPU_AARCH64 (=) | the -cpu model; set on the make command line, not from the environment |
QEMU_SMP_AARCH64 | the default -smp |
QEMU_EDK2_CODE_AARCH64, QEMU_EDK2_VARS_AARCH64 (?=) | the EDK2 search lists |
GARDEN_AARCH64_FEDORA_EDK2_SYSTEMS, GARDEN_AARCH64_JAMMY_EDK2_SYSTEMS (?=) | which systems boot the older builds |
GARDEN_AARCH64_PREFIX (environment) | appends a self-built QEMU's share/qemu firmware |
opencloudos-cloud-9 is the only loongarch64 system, also built for x86_64 and aarch64: image-garden make opencloudos-cloud-9.loongarch64.run.
Loongarch64 is one of rulegen.py's six architectures (rulegen.py:23-29). The older release notes added the machine "No distribution cloud images are available for loongarch64 yet" (NEWS:346-351); this release adds opencloudos-cloud-9, "image-garden's first loongarch64 system" (NEWS:52-53).The download names build 20260922.0 of 9.6, the same on x86_64, aarch64 and loongarch64, checked against the .sha256 file next to the image. All three boot with UEFI.
20260922.0 of 9.6 and its .sha256 file over https from the project's own mirror, and boot with UEFI (data/opencloudos.ini:13-32).SHA256SUMS=@URL@.sha256, Boot=efi and Release=9 (data/opencloudos.ini:13-32); @URL@ expands to the resolved image URL and is allowed only in SHA256SUMS and SHA512SUMS (rulegen.py:51-58, data/README.md:62-67).The URL names build 20260922.0 of 9.6; SHA256SUMS=@URL@.sha256 takes the checksum file next to the image. Boot=efi, Release=9.
20260922.0 of 9.6, SHA256SUMS=@URL@.sha256, Boot=efi and Release=9 (data/opencloudos.ini:13-32).@URL@ expands to the resolved image URL and is allowed only in SHA256SUMS and SHA512SUMS (rulegen.py:51-58, data/README.md:62-67)..sha256 files are fetched over https from the project's own mirror, like every image (data/opencloudos.ini:4-7, data/opencloudos.ini:13-32).qemu-system-loongarch64 -cpu max -machine virt, -smp 1 (4 on a loongarch64 host), -m 2048, two pflash drives, virtio-blk and virtio-net-pci.
QEMU_SYSTEM_LOONGARCH64_MACHINE = virt, QEMU_CPU_LOONGARCH64 = max, QEMU_SMP_LOONGARCH64 = 1, the network -netdev user with virtio-net-pci, and the EFI command line with two pflash drives (mk/010-qemu-loongarch64.mk:3-23). Unlike x86_64 and aarch64, the network option has no -smbios type=41 entry.ruleset_loongarch64_efi (rulegen.py:669-686) is printed for Boot=efi (rulegen.py:815-817); a loongarch64 section without it, or with another value, stops rulegen.py with has no Boot=, use efi for loongarch64 or which loongarch64 does not support, use efi (rulegen.py:300-333)./usr/share/qemu-efi-loongarch64/QEMU_EFI.fd (Debian, Ubuntu) or /usr/share/edk2/loongarch64/QEMU_EFI.fd (Fedora), then the snap component's or $GARDEN_LOONGARCH64_PREFIX's edk2-loongarch64-code.fd.
edk2-loongarch64-code.fd and -vars.fd, and GARDEN_LOONGARCH64_PREFIX (mk/010-qemu-loongarch64.mk:76-94); the copies and their qcow2 conversion (mk/010-qemu-loongarch64.mk:102-114).GARDEN_LOONGARCH64_PREFIX=/usr/local (Dockerfile:102).The snap's qemu-loongarch64 component carries share/qemu/efi-virtio.rom, the option ROM of the virtio-net-pci card, next to edk2-loongarch64-code.fd and -vars.fd.
edk2-loongarch64-code.fd, edk2-loongarch64-vars.fd and efi-virtio.rom (snap/snapcraft.yaml:380-413).virtio-net-pci (mk/010-qemu-loongarch64.mk:7-9). That QEMU loads the card's ROM by default and fails to create the card without it, and that the container's make install of QEMU installs the ROMs, are QEMU's behaviour (derived).Snap: snap install image-garden+qemu-loongarch64. Container: loongarch64-softmmu and GARDEN_LOONGARCH64_PREFIX. Ubuntu: qemu-system-misc and qemu-efi-loongarch64.
qemu-system-loongarch64 prints a notice box, "It seems that the component with QEMU loongarch64 is not installed", and the command snap install image-garden+qemu-loongarch64 (qemu-stubs/qemu-system-loongarch64:9-31). The component for the host's architecture is installed on refresh; others by hand (README.md:309-320).loongarch64-softmmu (Dockerfile:33), and its prefix variable points at that build's firmware (Dockerfile:102).loongarch64: [el] installs qemu-efi-loongarch64 qemu-system-misc on Ubuntu and tests opencloudos-cloud-9 with a 30 minute timeout (.gitlab-ci.yml:1004-1015); like every emulated job it only boots each image once (GARDEN_TEST_BOOT_ONLY) and has allow_failure: true, because the CI server is slow (.gitlab-ci.yml:663-690).Next: six architectures, UEFI firmware per system, the support matrix, the container in CI, the snap and the .run script.
Read in data/opencloudos.ini, mk/010-qemu-loongarch64.mk, rulegen.py, snap/snapcraft.yaml, qemu-stubs/qemu-system-loongarch64, the Dockerfile and .gitlab-ci.yml of image-garden at the tag in garden.commit ("code"). What QEMU does with an option ROM is derived from QEMU's behaviour. Nothing was run for this page.
| System | Architecture | Boot | Image |
|---|---|---|---|
opencloudos-cloud-9.x86_64 | x86_64 | efi | OpenCloudOS-GenericCloud-9.6-20260922.0.x86_64.qcow2 |
opencloudos-cloud-9.aarch64 | aarch64 | efi | OpenCloudOS-GenericCloud-9.6-20260922.0.aarch64.qcow2 |
opencloudos-cloud-9.loongarch64 | loongarch64 | efi | OpenCloudOS-GenericCloud-9.6-20260922.0.loongarch64.qcow2 |
Each from https://mirrors.opencloudos.tech/opencloudos/9.6/images/qcow2/ARCH/20260922.0/, checked against the .sha256 file next to it.
| Option | Value | Variable |
|---|---|---|
| program | qemu-system-loongarch64 | QEMU_SYSTEM_LOONGARCH64 |
-machine | virt | QEMU_SYSTEM_LOONGARCH64_MACHINE |
-cpu | max | QEMU_CPU_LOONGARCH64 |
-smp | 1, or 4 on a loongarch64 host | QEMU_SMP_LOONGARCH64, QEMU_SMP_OPTION |
-m | 2048 | QEMU_MEM_OPTION |
| firmware | two pflash drives | QEMU_BOOT_FIRMWARE_OPTION |
| network | -netdev user, virtio-net-pci | QEMU_NET_OPTION |
/usr/share/qemu-efi-loongarch64/QEMU_EFI.fd and QEMU_VARS.fd (Debian, Ubuntu: qemu-efi-loongarch64)/usr/share/edk2/loongarch64/QEMU_EFI.fd and QEMU_VARS.fd (Fedora: edk2-loongarch64)qemu-loongarch64/share/qemu/edk2-loongarch64-code.fd and -vars.fdGARDEN_LOONGARCH64_PREFIX: PREFIX/share/qemu/edk2-loongarch64-code.fd and -vars.fd| Install | Emulator | Firmware | efi-virtio.rom |
|---|---|---|---|
| Snap | image-garden+qemu-loongarch64 component | in the component | in the component |
| Container | built with loongarch64-softmmu | QEMU's own, via the prefix | QEMU's own |
| Ubuntu | qemu-system-misc | qemu-efi-loongarch64 | with QEMU (derived) |
Ten Ubuntu systems, 14.04 to 26.10, all little-endian and named .ppc64el: image-garden make ubuntu-cloud-24.04.ppc64el.run.
.ppc64el": 14.04, 16.04, 18.04, 20.04, 22.04, 24.04, 25.04, 25.10, 26.04, 26.10 (README.md:692-697). No other distribution has a ppc64 system, and there is no big-endian ppc64 system.Arch=ppc64 and no Boot; no other INI file has Arch=ppc64 (counted at the commit: 10 sections).[ubuntu-cloud-24.04.ppc64el] has Arch=ppc64; GARDEN_HOST_ARCH maps ppc64le to ppc64; define-instance takes the architecture from Arch.
[ubuntu-cloud-24.04.ppc64el] has Arch=ppc64 (data/ubuntu.ini:264-268). rulegen.py requires the section name to contain the Arch value ("Suspicious image") and, for architectures other than x86\_64 and aarch64, the URL too ("Suspicious URL") (rulegen.py:396-416).all:: and fetch compare GARDEN_ARCH with the Arch value (rulegen.py:453-459, rulegen.py:480-484); ppc64 sections get ruleset_ppc64 (rulegen.py:707-724, rulegen.py:820-821).GARDEN_HOST_ARCH := $(patsubst ppc64le,ppc64,$(shell uname -m)), the default of GARDEN_ARCH (mk/000-garden.mk:14-18); the native vCPU count is set on QEMU_SMP_ followed by that name upper-cased (mk/010-qemu.mk:5-6).define-instance takes the QEMU architecture from the base's _SYSTEM_arch metadata, written by rulegen.py from Arch, and compares it with GARDEN_ARCH for all:: (mk/020-instances.mk:53-65).define-instance appends GARDEN_ARCH, ppc64 there, and looks for ubuntu-cloud-24.04.ppc64, which has no metadata: the instance gets no boot type and no .run or .qcow2 rule (mk/020-instances.mk:31-39, mk/020-instances.mk:84-146). Derived from the code, not run.qemu-system-ppc64 and the qemu-ppc64 component, the system ubuntu-cloud-24.04.ppc64el, and a host whose uname -m says ppc64le, which image-garden counts as ppc64.
qemu-system-ppc64 and the snap's component qemu-ppc64 (mk/010-qemu-ppc64.mk:3, snap/snapcraft.yaml:87-92); the system is named ubuntu-cloud-24.04.ppc64el (data/ubuntu.ini:264-268).uname -m is ppc64le, image-garden uses ppc64 as the host architecture: "On a ppc64le host the ppc64 systems are native: "all" makes them and they get the native vCPU count" (NEWS:19-20, mk/000-garden.mk:14-18).$(uname -m) to the system name (README.md:740-745), which on a POWER host gives ppc64le; see the gotchas.qemu-system-ppc64 -machine pseries -cpu power9, -smp 1 (4 on POWER), -m 2048; every device on PCI; QEMU's SLOF boots the disk with bootindex=0.
QEMU_SYSTEM_PPC64_MACHINE = pseries, QEMU_CPU_PPC64 = power9, QEMU_SMP_PPC64 = 1, -netdev user with virtio-net-pci, and the disk -device virtio-blk,drive=drive0,bootindex=0; no firmware option (mk/010-qemu-ppc64.mk:3-21). -m 2048, -nographic and -device virtio-rng-pci are common to every architecture (mk/010-qemu.mk:5-13, mk/010-qemu.mk:45).efi-virtio.rom, slof.bin, u-boot-sam460.bin, vgabios-stdvga.bin, vgabios-virtio.bin, vof.bin and vof-nvram.bin (snap/snapcraft.yaml:409-411).virtio-blk to virtio-blk-pci on this machine are QEMU's behaviour (derived).platform, the default without Boot (rulegen.py:300-333). ruleset_ppc64 adds the seed to the provisioning boot as -device virtio-blk,drive=drive1 (rulegen.py:707-724).On a ppc64le host with KVM: accel=kvm:tcg and -smp 4. Elsewhere TCG and -smp 1; one image took up to 9.8 minutes to make and boot on x86_64.
.run script asks qemu-system-ppc64 -accel help and uses accel=kvm:tcg when kvm is listed, else accel=tcg (mk/010-qemu-ppc64.mk:31, mk/010-qemu-ppc64.mk:38).uname -m is ppc64le (mk/010-qemu-ppc64.mk:6, mk/010-qemu.mk:5-6, mk/000-garden.mk:14-18). The README lists ppc64le hosts as tier 3, "Native where KVM is available" (README.md:389-396).-smp 2 on an x86\_64 machine (.gitlab-ci.yml:993-1002).-cpu power9 needs a host that can run a POWER9 guest, POWER9 or later in compatibility mode; QEMU_CPU_PPC64 can be set on the make command line or in .image-garden.mk (derived).Stage ppc64el: two jobs on x86_64 runners with ARCH: ppc64el, GARDEN_TEST_BOOT_ONLY, -smp 2, 40 minutes per system, allow_failure: true.
QEMU_SMP_OPTION: -smp 2 and QEMU_MEM_OPTION: -m 1024 (.gitlab-ci.yml:568-569); .systems-emulated runs on x86\_64 runners tagged qemu-emulated, GARDEN_TEST_BOOT_ONLY: "1", GARDEN_CI_SYSTEM_TIMEOUT: 40m, allow_failure: true, manual outside version tags (.gitlab-ci.yml:663-690).ppc64el: [ubuntu 1/2] (14.04 to 22.04, 80 minutes, "25.9 minutes on novigrad; calvin took up to 9.4 for one") and ppc64el: [ubuntu 2/2] (24.04 to 26.10, 85 minutes, "28.5 minutes on novigrad; calvin took up to 9.8 for one"), both with ARCH: ppc64el (.gitlab-ci.yml:982-1002).tests/ci/run-systems.sh knows ppc64el as an architecture suffix and makes SYSTEM.ARCH.run (tests/ci/run-systems.sh:38, tests/ci/run-systems.sh:62-72). The CI installs Ubuntu's qemu-system-ppc package (.gitlab-ci.yml:292-310).Snap: snap install image-garden+qemu-ppc64. Container: ppc64-softmmu, no prefix. Ubuntu: qemu-system-ppc.
qemu-ppc64 component: "This component contains the ppc64 64-bit system emulator (QEMU)" (snap/snapcraft.yaml:87-92), with qemu-system-ppc64, the keymaps, efi-virtio.rom, slof.bin, u-boot-sam460.bin, vgabios-stdvga.bin, vgabios-virtio.bin, vof.bin and vof-nvram.bin (snap/snapcraft.yaml:409-411).+pkgproxy (snap/hooks/install:6-14); on an x86\_64 host the ppc64 component is added by hand (README.md:309-324).qemu-system-ppc64 prints "It seems that the component with QEMU ppc64 is not installed" and snap install image-garden+qemu-ppc64, and exits 1 (qemu-stubs/qemu-system-ppc64:9-31). The first QEMU to run is the provisioning boot, after the download.ppc64-softmmu (Dockerfile:33); it sets GARDEN_*_PREFIX only for the four efi architectures (Dockerfile:98-102).qemu-system-ppc package. Distribution packages of image-garden may be older than the upstream release (the maintainer's statement).qemu-$(uname -m) with _ made - (snap/hooks/install:7, snap/hooks/post-refresh:11). On a POWER host that is qemu-ppc64le, a component the snap does not have. Whether the snap is published for POWER is not in the tree; suspected, not run..qcow2 rule's provisioning boot (rulegen.py:716-723). image-garden's CI installs qemu-system-ppc (.gitlab-ci.yml:292-310).Little-endian, like a PC. Watch for 64 KiB pages, unsigned char, and uname -m giving ppc64le: spread backends need ARCH=ppc64el, instances the full base name.
char is unsigned in the POWER Linux ABI (derived: general knowledge, not in image-garden's tree). Use sysconf(_SC_PAGESIZE) rather than 4096.$(uname -m) (README.md:740-745); image-garden's own spread.yaml appends $ARCH, defaulting to uname -m (spread.yaml:43-47). On a POWER host uname -m is ppc64le; set ARCH=ppc64el, or use the system name with its suffix.ubuntu-cloud-24.04 alone, define-instance appends ppc64 there and finds no such system (mk/020-instances.mk:31-39); give the full ubuntu-cloud-24.04.ppc64el. Derived from the code, not run.ARCH: ppc64el, and tests/ci/run-systems.sh lists ppc64el among its architectures (.gitlab-ci.yml:982-1002, tests/ci/run-systems.sh:38).Next: six architectures, s390x, Ubuntu cloud images, named instances, spread names, snap components and the .run script.
Read in mk/010-qemu-ppc64.mk, mk/010-qemu.mk, mk/000-garden.mk, mk/020-instances.mk, rulegen.py, data/ubuntu.ini, snap/snapcraft.yaml, the snap's hooks, qemu-stubs/qemu-system-ppc64, the Dockerfile, spread.yaml, .gitlab-ci.yml, NEWS and the README of image-garden at the commit in garden.commit ("code"). The timings are the comments in .gitlab-ci.yml. What QEMU does with the device names and firmware on pseries, page sizes, the C ABI and KVM CPU compatibility are general knowledge ("derived"). Nothing was run for this page.
| Fact | Value | Where |
|---|---|---|
| QEMU binary | qemu-system-ppc64; in the snap the image-garden.qemu-system-ppc64 app | QEMU_SYSTEM_PPC64 |
| Machine | pseries | QEMU_SYSTEM_PPC64_MACHINE |
| CPU | power9 | QEMU_CPU_PPC64 |
| vCPUs | 1, or 4 on a ppc64le host | QEMU_SMP_PPC64, QEMU_SMP_OPTION |
| Memory | 2048 MiB | QEMU_MEM_SIZE, QEMU_MEM_OPTION |
| Accelerator | kvm:tcg when QEMU lists KVM, else tcg | QEMU_ACCEL_MACHINE_PROP |
| Disk | -device virtio-blk,drive=drive0,bootindex=0, virtio-blk-pci (derived) | QEMU_STORAGE_OPTION |
| Seed (provisioning boot) | a second virtio-blk, media=cdrom | the .qcow2 rule |
| Network | -netdev user, -device virtio-net-pci | QEMU_NET_OPTION |
| Random numbers | -device virtio-rng-pci | QEMU_RNG_OPTION |
| Display | -nographic | QEMU_DISPLAY_OPTION |
| Boot | platform: no firmware files; QEMU's SLOF (derived) | |
| Snap component | qemu-ppc64: qemu-system-ppc64, keymaps, efi-virtio.rom, slof.bin, u-boot-sam460.bin, vgabios-stdvga.bin, vgabios-virtio.bin, vof.bin, vof-nvram.bin | snap/snapcraft.yaml |
| Container | QEMU built with ppc64-softmmu; no prefix variable | Dockerfile |
| Ubuntu package | qemu-system-ppc | |
| Byte order | little-endian (all systems are ppc64el) |
Sources: mk/010-qemu-ppc64.mk:3-21, mk/010-qemu.mk:5-13, mk/000-garden.mk:14-18, snap/snapcraft.yaml:409-411, Dockerfile:33.
| System | Image |
|---|---|
ubuntu-cloud-14.04.ppc64el | trusty-server-cloudimg-ppc64el-disk1.img |
ubuntu-cloud-16.04.ppc64el | xenial-server-cloudimg-ppc64el-disk1.img |
ubuntu-cloud-18.04.ppc64el | bionic-server-cloudimg-ppc64el.img |
ubuntu-cloud-20.04.ppc64el | focal-server-cloudimg-ppc64el.img |
ubuntu-cloud-22.04.ppc64el | jammy-server-cloudimg-ppc64el.img |
ubuntu-cloud-24.04.ppc64el | noble-server-cloudimg-ppc64el.img |
ubuntu-cloud-25.04.ppc64el | ubuntu-25.04-server-cloudimg-ppc64el.img |
ubuntu-cloud-25.10.ppc64el | questing-server-cloudimg-ppc64el.img |
ubuntu-cloud-26.04.ppc64el | resolute-server-cloudimg-ppc64el.img |
ubuntu-cloud-26.10.ppc64el | stonking-server-cloudimg-ppc64el.img |
All from cloud-images.ubuntu.com, checked against the release's SHA256SUMS, all booting platform. See Ubuntu cloud images and the support matrix.
| Spelling | Where you meet it |
|---|---|
ppc64 | the emulator qemu-system-ppc64, the snap component qemu-ppc64, QEMU_SMP_PPC64, QEMU_CPU_PPC64 |
ppc64el | system names: image-garden make ubuntu-cloud-24.04.ppc64el.run, image-garden allocate ubuntu-cloud-24.04.ppc64el, the base of a named instance, ARCH for a spread backend |
ppc64le | uname -m on a POWER host; image-garden treats that host as ppc64 |
Arch=ppc64; rulegen.py checks that the section name and URL contain ppc64 (rulegen.py:396-416) and gives them ruleset_ppc64 (rulegen.py:707-724).GARDEN_HOST_ARCH maps ppc64le to ppc64 and is the default GARDEN_ARCH (mk/000-garden.mk:14-18), so all:: and fetch match the ppc64 systems on a POWER host and QEMU_SMP_PPC64 is 4 there (mk/010-qemu.mk:5-6).define-instance takes the QEMU architecture from the base's Arch (mk/020-instances.mk:53-65).What ubuntu-cloud-24.04.ppc64el.run runs with every default, outside the snap, on an x86\_64 host:
qemu-system-ppc64 -cpu power9 -machine pseries,accel=tcg \ -m 2048 -smp 1 -nographic \ -drive file=ubuntu-cloud-24.04.ppc64el.qcow2,if=none,format=qcow2,id=drive0,media=disk,cache=writeback,discard=unmap \ -device virtio-blk,drive=drive0,bootindex=0 \ -device virtio-rng-pci \ -netdev user,id=netdev0 -device virtio-net-pci,netdev=netdev0,id=net0
-netdev user also takes QEMU_NETDEV_USER_EXTRA, which allocate sets to forward SSH (image-garden:1107), and the pkgproxy bridge when one is in use; see the .run script.
| Job | Systems | Timeout | Recorded time |
|---|---|---|---|
ppc64el: [ubuntu 1/2] | 14.04, 16.04, 18.04, 20.04, 22.04 | 80m | 25.9 minutes; up to 9.4 for one |
ppc64el: [ubuntu 2/2] | 24.04, 25.04, 25.10, 26.04, 26.10 | 85m | 28.5 minutes; up to 9.8 for one |
Both run on x86\_64 runners tagged qemu-emulated with ARCH: ppc64el, boot each image once with -smp 2 and -m 1024, 40 minutes per system, allow_failure: true (.gitlab-ci.yml:663-690, .gitlab-ci.yml:982-1002).
sysconf(_SC_PAGESIZE), do not assume 4096.char is unsigned on POWER.riscv64 guests are emulated on a PC; a riscv64 host is tier 3, native only with KVM. image-garden make ubuntu-cloud-24.04.riscv64.run uses the riscv64 image from the same SHA256SUMS as the x86_64 example.
ubuntu-cloud-24.04.riscv64 downloads noble-server-cloudimg-riscv64.img, checked against https://cloud-images.ubuntu.com/noble/current/SHA256SUMS, the list of the x86\_64 example.[ubuntu-cloud-24.04.riscv64] (data/ubuntu.ini:251-256), beside the x86\_64 one (:237-242).qemu-system-riscv64 -machine virt,acpi=off -cpu max, accel=tcg and -smp 1 on a PC, -m 2048, virtio-net-pci without -smbios type=41.
virt,acpi=off, CPU max, 1 vCPU unless the host is riscv64, then 4; memory 2048 MiB; network -netdev user with virtio-net-pci and no -smbios type=41, which x86\_64 and aarch64 have.max enables every extension QEMU implements; a QEMU for riscv64 on another host has no KVM to offer (all derived from QEMU's documentation).QEMU_MEM_OPTION="-m 4096" and QEMU_SMP_OPTION change one run; see the .run script.QEMU loads OpenSBI; EDK2 comes from /usr/share/qemu-efi-riscv64/RISCV_VIRT_CODE.fd, Fedora's /usr/share/edk2/riscv/, the snap's component or a prefix, sized to 32 MiB.
edk2-riscv-code.fd, edk2-riscv-vars.fd, efi-virtio.rom and opensbi-riscv64-generic-fw_dynamic.bin, "the firmware QEMU loads by default" for the machine (snap/snapcraft.yaml:404-406, tests/snap/qemu-components/task.yaml:54-75). That OpenSBI runs in machine mode and starts EDK2 from pflash is QEMU's behaviour (derived)./usr/share/qemu-efi-riscv64/RISCV_VIRT_CODE.fd (Debian and Ubuntu's qemu-efi-riscv64), /usr/share/edk2/riscv/RISCV_VIRT_CODE.fd (Fedora) and /usr/share/qemu/ovmf-riscv64-code.bin (openSUSE, commit ef5bc3c), then in the snap's component, then under $GARDEN_RISCV64_PREFIX/share/qemu/; the variables likewise. Which distribution installs which path is derived.truncate pads a shorter file and cuts a longer one (derived).ubuntu-cloud-24.04, 25.04, 25.10, 26.04, 26.10 and fedora-cloud-42 to 45, each .riscv64. No Ubuntu Core.
https://dl.fedoraproject.org/pub/alt/risc-v/release/RELEASE/Cloud/riscv64/images/, each a dated build such as Fedora-Cloud-Base-Generic-45-20261022.0.riscv64.qcow2, checked against the .sha256 file beside it.make all on a riscv64 host leaves it out.data/ubuntu.ini; Ubuntu Core's systems exist for x86\_64 and aarch64 only (mk/050-ubuntu-core.mk:4-7), and join all:: only there (commit 073886d).Snap: snap install image-garden+qemu-riscv64. Container: riscv64-softmmu and GARDEN_RISCV64_PREFIX, on x86_64 and aarch64 hosts. Ubuntu: qemu-system-riscv and qemu-efi-riscv64.
qemu-riscv64 holds "the RISC-V 64-bit system emulator (QEMU) as well as the corresponding EFI firmware (EDK2)" (snap/snapcraft.yaml:74-80) and OpenSBI (:404-406).snap install image-garden+qemu-riscv64 (qemu-stubs/qemu-system-riscv64:9-31).riscv64-softmmu (Dockerfile:33) and sets GARDEN_RISCV64_PREFIX=/usr/local (Dockerfile:98-102); its images are built for x86\_64 and aarch64 only (.gitlab-ci.yml:1238-1276).qemu-system-riscv and qemu-efi-riscv64. Distribution packages may be older than the upstream release (the maintainer's statement).make all builds the systems of GARDEN_ARCH, your host's architecture unless you set it, as in image-garden make GARDEN_ARCH=riscv64 all (mk/000-garden.mk:16-18, rulegen.py:456-459).mk/010-qemu-riscv64.mk: virt,acpi=off, max, no -smbios, truncate --size 32MiB. CI: the riscv64 stage, GARDEN_TEST_BOOT_ONLY, allow_failure: true.
QEMU_SYSTEM_RISCV64_MACHINE = virt,acpi=off, QEMU_CPU_RISCV64 = max, QEMU_SMP_RISCV64 = 1, the network option without -smbios (mk/010-qemu-riscv64.mk:3-9).truncate --size 32MiB (mk/010-qemu-riscv64.mk:100-116); .DELETE_ON_ERROR exists so that "firmware that was copied but not resized, is not considered up to date" (mk/000-garden.mk:4-7). The snap bundles GNU truncate, as the base's uutils truncate was blocked by the sandbox and "broke building EFI variable storage for riscv64 systems" (NEWS.snappy:167-170).BOOT_BY_ARCH and ruleset_riscv64_efi (rulegen.py:302-309, rulegen.py:650-667)..systems-emulated (runners tagged qemu-emulated, GARDEN_TEST_BOOT_ONLY, allow_failure, version tags or manual) (.gitlab-ci.yml:663-690); the riscv64 jobs, with 65 to 90 minute timeouts, "20.4 minutes on novigrad" for the four Fedora systems, "31 minutes on novigrad; calvin took up to 19.2 for one" for three Ubuntu ones (.gitlab-ci.yml:919-948).Allocate waits up to GARDEN_SSH_WAIT_TIMEOUT (600 s) for SSH before it reports the address. More vCPUs: QEMU_SMP_OPTION="-smp 4". For a big-endian guest use s390x.
--spread, allocate waits for the SSH banner before it prints the address, up to GARDEN_SSH_WAIT_TIMEOUT seconds (600 by default), then reports the address anyway (image-garden:1167-1203, image-garden.1:542-549). Spread allows one minute after allocation (the comment at image-garden:1168-1171); see waiting for SSH.kill-timeout is spread's per-task limit (spread's documentation, derived). QEMU runs each vCPU of a TCG guest in a thread of its own on hosts that support it (multi-threaded TCG, derived), so more vCPUs can help when the host has idle cores.Next: six architectures, the adhoc backend, the .run script, UEFI firmware, snap components, the container in CI and the support matrix.
Read in the README, mk/010-qemu-riscv64.mk, mk/010-qemu.mk, mk/000-garden.mk, rulegen.py, data/ubuntu.ini, data/fedora.ini, snap/snapcraft.yaml, qemu-stubs/qemu-system-riscv64, tests/snap/qemu-components/task.yaml, the Dockerfile, .gitlab-ci.yml, NEWS.snappy and the man page of image-garden at the commit in garden.commit ("code"). The timings are the CI comments' figures, not measured for this page. What OpenSBI, ACPI, the device tree, max and multi-threaded TCG do, distribution package paths, and byte order are derived. Nothing was run for this page.
| Fact | Value |
|---|---|
| QEMU program | qemu-system-riscv64; in the snap the image-garden.qemu-system-riscv64 app |
| Machine | virt,acpi=off |
| CPU | max |
| Accelerator | tcg on any other host; kvm:tcg only where QEMU lists KVM (a riscv64 host with KVM) |
| vCPUs | 1, or 4 on a riscv64 host |
| Memory | -m 2048 |
| Boot types | efi only |
| Firmware | OpenSBI (loaded by QEMU), then EDK2 RISCV_VIRT_CODE.fd and RISCV_VIRT_VARS.fd, copied to efi-code.riscv64.img and efi-vars.riscv64.img and truncated to 32 MiB |
| Network | -netdev user, virtio-net-pci, no -smbios |
| Snap component | qemu-riscv64: snap install image-garden+qemu-riscv64 |
| Container | QEMU with riscv64-softmmu, GARDEN_RISCV64_PREFIX=/usr/local; images for x86\_64 and aarch64 hosts only |
| Ubuntu packages | qemu-system-riscv, qemu-efi-riscv64 |
| Host tier | 3: experimental, native where KVM is available |
| Byte order | little-endian (derived) |
| System | Image |
|---|---|
ubuntu-cloud-24.04.riscv64, 25.04, 25.10, 26.04, 26.10 | cloud-images.ubuntu.com, …-server-cloudimg-riscv64.img, current build |
fedora-cloud-42.riscv64 to 45 | dl.fedoraproject.org/pub/alt/risc-v/release/, one dated build each, with its .sha256 file |
No Ubuntu Core, and no other family.
| What | How |
|---|---|
| allocate's wait for SSH | GARDEN_SSH_WAIT_TIMEOUT, seconds, 600 by default, with --spread |
| Spread's limit per task | kill-timeout in the task (spread, derived) |
| More vCPUs for one run | QEMU_SMP_OPTION="-smp 4" |
| More memory for one run | QEMU_MEM_OPTION="-m 4096" |
| Build all riscv64 systems on a PC | image-garden make GARDEN_ARCH=riscv64 all |
| Fact | Source |
|---|---|
| Program, machine, CPU, SMP, network | mk/010-qemu-riscv64.mk:3-9 |
| Firmware lists, copies, truncate | mk/010-qemu-riscv64.mk:75-116 |
| Native vCPU count, memory | mk/010-qemu.mk:5-12 |
| Efi only | rulegen.py:302-309 |
| Snap component | snap/snapcraft.yaml:74-80, :404-406 |
| SSH wait | image-garden:1167-1203 |
| CI stage and timings | .gitlab-ci.yml:663-690, :919-948 |
| Make variable | Effect |
|---|---|
QEMU_CPU_RISCV64 (=) | the -cpu model; set on the make command line, not from the environment |
QEMU_SMP_RISCV64 | the default -smp |
QEMU_EDK2_CODE_RISCV64, QEMU_EDK2_VARS_RISCV64 (?=) | the EDK2 search lists |
GARDEN_RISCV64_PREFIX (environment) | appends a self-built QEMU's share/qemu firmware |
Twelve s390x systems, Ubuntu 18.04 to 26.10 and Fedora 42 to 45, all big-endian: image-garden make ubuntu-cloud-24.04.s390x.run.
S390X is one of rulegen.py's six architectures (rulegen.py:23-29). The running example is data/ubuntu.ini:258-262; the first is data/ubuntu.ini:95-99, the Fedora sections run from data/fedora.ini:87-91 to data/fedora.ini:168-172. No other INI file has Arch=s390x (counted at the commit: 12 sections).qemu-system-s390x -machine s390-ccw-virtio -cpu qemu, -smp 1 (4 on s390x), -m 2048. virtio-blk is a ccw device here; virtio-net-pci and virtio-rng-pci sit on zPCI.
QEMU_SYSTEM_S390X is the snap's qemu-system-s390x app in the snap, else qemu-system-s390x from PATH; QEMU_SYSTEM_S390X_MACHINE = s390-ccw-virtio, QEMU_CPU_S390X = qemu, QEMU_SMP_S390X = 1, the network -netdev user with virtio-net-pci, and the disk -device virtio-blk,drive=drive0,bootindex=0 (mk/010-qemu-s390x.mk:3-21).-m 2048, -nographic, and -device virtio-rng-pci are common to every architecture; the host's own architecture gets 4 CPUs (mk/010-qemu.mk:5-13, mk/010-qemu.mk:45).virtio-blk to virtio-blk-ccw, a device on the channel subsystem, and places PCI devices such as virtio-net-pci and virtio-rng-pci on the machine's zPCI bus; the guest's kernel needs zPCI support for them, which the Ubuntu and Fedora kernels have (derived from QEMU's device aliases and the s390x PCI support; not run here).efi-virtio.rom, the option ROM file QEMU loads for a virtio-net-pci card (snap/snapcraft.yaml:407-408).-drive ...,media=cdrom with -device virtio-blk,drive=drive1 (rulegen.py:697-704).No firmware files: QEMU's s390-ccw.img loader boots the disk with bootindex=0. The seed is attached only for the provisioning boot.
.run command line has no firmware option; the disk has bootindex=0 (mk/010-qemu-s390x.mk:10-21).s390-ccw.img from QEMU's build (snap/snapcraft.yaml:407-408). That the s390-ccw-virtio machine loads it by default and that it boots the device with the lowest boot index is QEMU's behaviour (derived).make clean removes *.s390x.qcow2 (mk/010-qemu-s390x.mk:70-72).s390x sections have no Boot, so platform; rulegen.py prints ruleset_s390x: a .run rule without firmware and a .qcow2 rule with one provisioning boot.
platform, the default when Boot is not given; another value fails with "Image '...' has Boot=..., which s390x does not support, use platform" (rulegen.py:300-333). The running example has no Boot key (data/ubuntu.ini:258-262), and neither has any s390x section.ruleset_s390x for every s390x section: a .run rule that emits EMIT_QEMU_SYSTEM_S390X_RUN_COMMAND, and a .qcow2 rule that depends on the download and the seed ISO, creates the overlay with qemu-img create -b and runs QEMU_SYSTEM_S390X_CMDLINE with the seed, under set -o pipefail, into .qcow2.log (rulegen.py:688-705, rulegen.py:818-819).platform branch (mk/020-instances.mk:126-144).Without an s390x host, QEMU uses TCG and -smp 1. Making and booting one Ubuntu image took up to 16.2 minutes on x86_64; QEMU_SMP_OPTION adds CPUs.
.run script asks qemu-system-s390x -accel help each time and uses accel=kvm:tcg when kvm is listed, else accel=tcg (mk/010-qemu-s390x.mk:31, mk/010-qemu-s390x.mk:38). KVM for an s390x guest needs an s390x host (derived).-smp 2 on an x86\_64 machine (.gitlab-ci.yml:960-969).Stage s390x: three jobs on x86_64 runners, GARDEN_TEST_BOOT_ONLY, -smp 2, 40 minutes per system, allow_failure: true.
QEMU_SMP_OPTION: -smp 2 and QEMU_MEM_OPTION: -m 1024 (.gitlab-ci.yml:568-569); .systems-emulated runs on runners tagged qemu-emulated, linux, x86_64, sets GARDEN_TEST_BOOT_ONLY: "1" and GARDEN_CI_SYSTEM_TIMEOUT: 40m, allow_failure: true, and is manual outside version tags (.gitlab-ci.yml:663-690).tests/ci/run-systems.sh makes SYSTEM.ARCH.run, checks --query, and stops there (tests/ci/run-systems.sh:62-72).s390x: [fedora] 45 minutes, "12.9 minutes on novigrad; calvin took up to 8.2 for one"; s390x: [ubuntu 1/2] 105 minutes, "35.2 minutes on novigrad; calvin took up to 16.2 for one"; s390x: [ubuntu 2/2] 115 minutes, "39.9 minutes on novigrad; calvin took up to 18.7 for one" (.gitlab-ci.yml:950-981). The slide gives the first Ubuntu job's figure.qemu-system-s390x package (.gitlab-ci.yml:292-310).Snap: snap install image-garden+qemu-s390x. Container: s390x-softmmu, no prefix. Ubuntu: qemu-system-s390x.
qemu-s390x component: "This component contains the s390x 64-bit system emulator (QEMU)" (snap/snapcraft.yaml:81-86); the build gives it qemu-system-s390x, the keymaps, efi-virtio.rom and s390-ccw.img (snap/snapcraft.yaml:381-394, snap/snapcraft.yaml:407-408).+qemu-$(uname -m) (with _ made -) and +pkgproxy, so on an x86\_64 host the s390x component is added by hand (snap/hooks/install:6-14, README.md:309-324).qemu-system-s390x prints a notice box, "It seems that the component with QEMU s390x is not installed", and snap install image-garden+qemu-s390x, and exits 1 (qemu-stubs/qemu-system-s390x:9-31). s390x has no firmware to copy, so the first QEMU to run is the provisioning boot, after the download.s390x-softmmu (Dockerfile:33); it sets GARDEN_*_PREFIX only for the four efi architectures (Dockerfile:98-102).qemu-system-s390x package. Distribution packages of image-garden may be older than the upstream release (the maintainer's statement)..qcow2 rule's provisioning boot (rulegen.py:697-704).qemu-system-s390x package (.gitlab-ci.yml:292-310).Little-endian assumptions in file formats, hashes over raw structs and hand-made byte swaps fail on s390x; so does code that relies on signed char. Emulated jobs need long timeouts and should not block.
htonl/ntohl or explicit little-endian decoding, all give different results on s390x (derived: general architecture knowledge, not in image-garden's tree).char: the s390x Linux ABI makes plain char unsigned, as on aarch64 and POWER; x86\_64 makes it signed (derived).spread.yaml appends $ARCH, or uname -m, to the system name; on an x86\_64 host, set ARCH=s390x to test s390x (spread.yaml:43-47).allow_failure: true, and manual outside version tags (.gitlab-ci.yml:663-690).Next: six architectures, boot types, the support matrix, ppc64, snap components, the container in CI and the .run script.
Read in mk/010-qemu-s390x.mk, mk/010-qemu.mk, mk/000-garden.mk, rulegen.py, data/ubuntu.ini, data/fedora.ini, snap/snapcraft.yaml, snap/hooks/install, qemu-stubs/qemu-system-s390x, the Dockerfile, .gitlab-ci.yml and the README of image-garden at the commit in garden.commit ("code"). The CI timings are the comments in .gitlab-ci.yml. What QEMU does with the device names on s390x, that s390x is big-endian, and the C ABI notes are general knowledge ("derived"). Nothing was run for this page.
| Fact | Value | Where |
|---|---|---|
| QEMU binary | qemu-system-s390x; in the snap the image-garden.qemu-system-s390x app | QEMU_SYSTEM_S390X |
| Machine | s390-ccw-virtio | QEMU_SYSTEM_S390X_MACHINE |
| CPU | qemu | QEMU_CPU_S390X |
| vCPUs | 1, or 4 on an s390x host | QEMU_SMP_S390X, QEMU_SMP_OPTION |
| Memory | 2048 MiB | QEMU_MEM_SIZE, QEMU_MEM_OPTION |
| Accelerator | kvm:tcg when QEMU lists KVM, else tcg | QEMU_ACCEL_MACHINE_PROP |
| Disk | -device virtio-blk,drive=drive0,bootindex=0, a virtio-blk-ccw device (derived) | QEMU_STORAGE_OPTION |
| Seed (provisioning boot) | -device virtio-blk,drive=drive1, media=cdrom, also ccw (derived) | the .qcow2 rule |
| Network | -netdev user, -device virtio-net-pci, on zPCI (derived) | QEMU_NET_OPTION |
| Random numbers | -device virtio-rng-pci, on zPCI (derived) | QEMU_RNG_OPTION |
| Display | -nographic | QEMU_DISPLAY_OPTION |
| Boot | platform: no firmware files; QEMU's s390-ccw.img loader | |
| Snap component | qemu-s390x: qemu-system-s390x, keymaps, efi-virtio.rom, s390-ccw.img | snap/snapcraft.yaml |
| Container | QEMU built with s390x-softmmu; no GARDEN_S390X_PREFIX | Dockerfile |
| Ubuntu package | qemu-system-s390x | |
| Byte order | big-endian (derived) |
Sources: mk/010-qemu-s390x.mk:3-21, mk/010-qemu.mk:5-13, mk/010-qemu.mk:45, rulegen.py:300-333, rulegen.py:688-705, snap/snapcraft.yaml:407-408, Dockerfile:33.
| System | Image | Boot |
|---|---|---|
ubuntu-cloud-18.04.s390x | bionic-server-cloudimg-s390x.img | platform |
ubuntu-cloud-20.04.s390x | focal-server-cloudimg-s390x.img | platform |
ubuntu-cloud-22.04.s390x | jammy-server-cloudimg-s390x.img | platform |
ubuntu-cloud-24.04.s390x | noble-server-cloudimg-s390x.img | platform |
ubuntu-cloud-25.04.s390x | ubuntu-25.04-server-cloudimg-s390x.img | platform |
ubuntu-cloud-25.10.s390x | questing-server-cloudimg-s390x.img | platform |
ubuntu-cloud-26.04.s390x | resolute-server-cloudimg-s390x.img | platform |
ubuntu-cloud-26.10.s390x | stonking-server-cloudimg-s390x.img | platform |
fedora-cloud-42.s390x | Fedora-Cloud-Base-Generic-42-1.1.s390x.qcow2 | platform |
fedora-cloud-43.s390x | Fedora-Cloud-Base-Generic-43-1.6.s390x.qcow2 | platform |
fedora-cloud-44.s390x | Fedora-Cloud-Base-Generic-44-1.7.s390x.qcow2 | platform |
fedora-cloud-45.s390x | Fedora-Cloud-Base-Generic-45-1.4.s390x.qcow2 | platform |
Ubuntu's come from cloud-images.ubuntu.com with the release's SHA256SUMS; Fedora's from Fedora's secondary architectures tree (42 from its archive) with the image's CHECKSUM file. Sections: data/ubuntu.ini, data/fedora.ini:87-172. See the support matrix.
What ubuntu-cloud-24.04.s390x.run runs with every default, outside the snap, on an x86\_64 host:
qemu-system-s390x -cpu qemu -machine s390-ccw-virtio,accel=tcg \ -m 2048 -smp 1 -nographic \ -drive file=ubuntu-cloud-24.04.s390x.qcow2,if=none,format=qcow2,id=drive0,media=disk,cache=writeback,discard=unmap \ -device virtio-blk,drive=drive0,bootindex=0 \ -device virtio-rng-pci \ -netdev user,id=netdev0 -device virtio-net-pci,netdev=netdev0,id=net0
-netdev user also takes QEMU_NETDEV_USER_EXTRA, which allocate sets to forward SSH (image-garden:1107), and the pkgproxy bridge when one is in use; see the .run script. Arguments to the script go to QEMU after these.
| Job | Systems | Timeout | Recorded time |
|---|---|---|---|
s390x: [fedora] | fedora-cloud-42 to 45 | 45m | 12.9 minutes; up to 8.2 for one |
s390x: [ubuntu 1/2] | ubuntu-cloud 18.04, 20.04, 22.04, 24.04 | 105m | 35.2 minutes; up to 16.2 for one |
s390x: [ubuntu 2/2] | ubuntu-cloud 25.04, 25.10, 26.04, 26.10 | 115m | 39.9 minutes; up to 18.7 for one |
Each runs on an x86\_64 runner tagged qemu-emulated, boots each image once, with -smp 2 and -m 1024, 40 minutes per system, allow_failure: true; on version tags it runs, elsewhere by hand (.gitlab-ci.yml:663-690, .gitlab-ci.yml:950-981).
htonl, ntohl and friends rather than an unconditional byte swap; on s390x they do nothing, which is correct.char is unsigned on s390x; use signed char or int8_t where the sign matters.x86_64 is the tier 1 host and the widest column of the support matrix: every system name has an x86_64 build. image-garden make ubuntu-cloud-24.04.x86_64.run is this map's running example.
-accel help, the vCPU rule) is in six architectures; this deck says what is particular to x86\_64.[ubuntu-cloud-24.04.x86_64], Arch=x86_64, Boot=efi, Release=24.04 (data/ubuntu.ini:237-242); Ubuntu Core's systems (mk/050-ubuntu-core.mk:4-16).qemu-system-x86_64 -machine q35,accel=kvm:tcg -cpu max, -smp 4 on an x86_64 host and -smp 1 elsewhere, -m 2048. QEMU_SMP_OPTION and QEMU_MEM_OPTION override them for one run.
.run script runs -accel help when it starts and uses ,accel=kvm:tcg when kvm is listed, else ,accel=tcg; the host's own architecture gets 4 vCPUs, every other one 1 (six architectures).QEMU_SMP_OPTION and QEMU_MEM_OPTION from the environment replace the defaults for one run; see the .run script.-cpu model is written into the .run script when make creates it; it is not a run-time variable.max offers every feature the accelerator can" are QEMU's documentation (derived): under KVM max passes through what the host CPU supports, under TCG it is everything QEMU emulates.QEMU_SYSTEM_X86_64 (the snap's qemu-system-x86-64 app in the snap, else qemu-system-x86_64 from PATH), QEMU_SYSTEM_X86_64_MACHINE = q35, QEMU_CPU_X86_64 ?= max, QEMU_SMP_X86_64 = 1 (mk/010-qemu-x86_64.mk:4-7).-smp (mk/010-qemu-x86_64.mk:63-65); the overrides (:72-74); -cpu in the command array (:95).GARDEN_HOST_ARCH (mk/000-garden.mk:14-18), QEMU_MEM_SIZE = 2048 (mk/010-qemu.mk:9-12).-smbios type=41, as on aarch64 and unlike riscv64 (mk/010-qemu-x86_64.mk:8-11).Most systems boot efi, OVMF from per-system copies; six boot bios, QEMU's own BIOS. The +tpm systems get the Secure Boot pair, OVMF_CODE_4M.secboot.fd and OVMF_VARS_4M.ms.fd, on q35,smm=on.
amazonlinux-cloud-2, centos-cloud-9, centos-cloud-10, oracle-cloud-7, oracle-cloud-8 and oracle-cloud-9, all on x86\_64; their aarch64 builds, where they exist, boot efi. A bios system has no firmware files and no firmware option; the snap's component carries bios-256k.bin, the BIOS QEMU's PC machines load by default (snap/snapcraft.yaml:395-401; what QEMU loads is derived).X.efi-code.qcow2 and X.efi-vars.qcow2, copied from the first OVMF build found: the ovmf package's paths (Debian, Ubuntu, Arch, openSUSE), the snap's qemu-x86-64 component, then $GARDEN_X86_64_PREFIX/share/qemu/. The whole story is in UEFI firmware per system.OVMF_CODE_4M.secboot.fd and OVMF_VARS_4M.ms.fd from the same build (Ubuntu's ovmf package, or the snap's component), for the four +tpm systems only; see Secure Boot and TPM.efi and bios on x86\_64 (rulegen.py:302-309) and prints ruleset_x86_64_efi or ruleset_x86_64_bios (rulegen.py:804-808). The sections: data/amazonlinux.ini:8-14, data/centos.ini:8-26, data/oracle.ini:10-35.q35,smm=on (mk/050-ubuntu-core.mk:55-61).61 cloud systems and 13 Ubuntu Core systems. Only on x86_64: archlinux-cloud, oracle-cloud-7, the 13 end-of-life Ubuntu interims, ubuntu-core-16, -18, -20 and the four +tpm systems.
.x86_64 build (counted at the pinned commit), and 13 Ubuntu Core systems; the full table is in the support matrix and in this deck's reference.archlinux-cloud, oracle-cloud-7, and the 13 end-of-life interims 16.10 to 24.10, "x86\_64, fetched from archived release URLs", whose apt uses old-releases.ubuntu.com (README.md:684-697); Ubuntu Core 16, 18 and 20 and the four +tpm systems (README.md:699-718).image-garden make list-systems prints every system, one per line; the grep is ordinary shell. image-garden make all builds every system of your host's architecture.list-systems prints GARDEN_SYSTEMS (mk/000-garden.mk:85-87); all:: collects the systems of GARDEN_ARCH, the host's architecture by default (rulegen.py:456-459, mk/000-garden.mk:16-18).Snap: the qemu-x86-64 component, installed on x86_64 hosts by the install hook. Container: x86_64-softmmu plus the ovmf package. Ubuntu: qemu-system-x86 and ovmf, and swtpm for the +tpm systems.
qemu-x86-64 on an x86\_64 host; a snap installed from a file installs no component (snap/hooks/install:6-13, snap/hooks/post-refresh:9-28). The component carries "the 64-bit x86 system emulator (QEMU) as well as the corresponding EFI firmware (EDK2) and the Secure Boot EFI firmware of Ubuntu (OVMF)" (snap/snapcraft.yaml:59-66).snap install image-garden+qemu-x86-64 (qemu-stubs/qemu-system-x86_64:9-31), and making an efi system stops with "install qemu-x86-64 component to use x86\_64 emulation".x86_64-softmmu among six targets (Dockerfile:33), installs ovmf and swtpm (Dockerfile:78-91) and points GARDEN_X86_64_PREFIX at its QEMU's firmware (Dockerfile:98-102). It is published for x86\_64 and aarch64 hosts (.gitlab-ci.yml:1238-1276).qemu-system-x86, ovmf, and swtpm for the +tpm systems, with qemu-utils and xorriso for any system. Distribution packages may be older than the upstream release (the maintainer's statement).mk/010-qemu-x86_64.mk: program, machine, CPU, SMP, the EFI and BIOS command lines and the .run emitters. rulegen.py accepts Boot=efi or bios and prints ruleset_x86_64_efi or _bios.
QEMU_SYSTEM_X86_64_EFI_CMDLINE and _BIOS_CMDLINE for the provisioning boot (:12-39); EMIT_QEMU_SYSTEM_X86_64_EFI_RUN_COMMAND, …_WITH_TPM and …_BIOS_RUN_COMMAND for the .run script (:46-108, :218-259). The TPM variant adds EMIT_SWTPM_START and -global driver=cfi.pflash01,property=secure,value=on (:134-135).BOOT_BY_ARCH and load_boot: x86\_64 takes efi or bios; a missing or other value is an error naming the section and the allowed values (rulegen.py:300-333); the rule sets (rulegen.py:593-629), chosen at rulegen.py:804-808.QEMU_CPU_X86_64 use ?=; QEMU_SYSTEM_X86_64_MACHINE and QEMU_SMP_X86_64 use =, which a target-specific assignment such as the +tpm one overrides (mk/050-ubuntu-core.mk:55)..systems-x86_64 runs on runners tagged linux, x86_64, kvm; the stage blocks "but for the systems past their end of life" (.gitlab-ci.yml:78-91, :624-633).EL 10 needs x86-64-v3: QEMU_CPU_X86_64=Haswell, with QEMU_ACCEL_MACHINE_PROP=,accel=tcg on an older host. The snap writes x86-64 with dashes. For a big-endian guest use s390x.
QEMU_CPU_X86_64=Haswell or newer if needed" (README.md:677-681). With KVM, -cpu max offers what the host CPU has (derived), so a host without x86-64-v3 cannot give it. Under TCG, set both: image-garden make QEMU_CPU_X86_64=Haswell SYSTEM.run and run it with QEMU_ACCEL_MACHINE_PROP=,accel=tcg.QEMU_CPU_X86_64 is set with ?=, so it can come from the environment as well as the make command line (mk/010-qemu-x86_64.mk:6); it is written into the .run script when make creates it, so remake the script after changing it. QEMU_ACCEL_MACHINE_PROP is read when the script runs (mk/010-qemu-x86_64.mk:72).qemu-system-x86-64 and runs qemu-system-x86_64 (snap/snapcraft.yaml:149-152, mk/010-qemu-x86_64.mk:3-4)./dev/kvm warning and its advice (image-garden:670-709) are shown in six architectures.QEMU_CPU_X86_64: Haswell and QEMU_ACCEL_MACHINE_PROP: ",accel=tcg" (commit 128bbd5, "ci: disable kvm on emulated x86_64-v3").Next: boot types, UEFI firmware, Secure Boot and the TPM, the support matrix, snap components, the container in CI and the .run script.
Read in the README, mk/010-qemu-x86_64.mk, mk/010-qemu.mk, mk/000-garden.mk, mk/050-ubuntu-core.mk, rulegen.py, data/*.ini, snap/snapcraft.yaml, snap/hooks/install, qemu-stubs/qemu-system-x86_64, the Dockerfile and .gitlab-ci.yml of image-garden at the commit in garden.commit ("code"). The system counts were taken from the INI files at that commit. What q35, -cpu max and the BIOS do inside QEMU, and byte order, are derived from QEMU's documentation and general knowledge. Nothing was run for this page.
| Fact | Value |
|---|---|
| QEMU program | qemu-system-x86_64; in the snap the image-garden.qemu-system-x86-64 app |
| Machine | q35; q35,smm=on for the +tpm systems |
| CPU | max |
| Accelerator | kvm:tcg when QEMU lists KVM, else tcg |
| vCPUs | 4 on an x86\_64 host, 1 elsewhere |
| Memory | -m 2048 |
| Boot types | efi and bios |
| Firmware (efi) | OVMF, copied to efi-code.x86_64.img and efi-vars.x86_64.img, then per system X.efi-code.qcow2 and X.efi-vars.qcow2 |
| Firmware (Secure Boot) | OVMF_CODE_4M.secboot.fd and OVMF_VARS_4M.ms.fd, copied to efi-secboot-code.x86_64.img and efi-secboot-vars.x86_64.img |
| Firmware (bios) | none; QEMU's own BIOS |
| Network | -netdev user, virtio-net-pci, -smbios type=41 |
| Snap component | qemu-x86-64, installed by the snap on x86\_64 hosts |
| Container | QEMU with x86_64-softmmu, ovmf, swtpm; images for x86\_64 and aarch64 hosts |
| Ubuntu packages | qemu-system-x86, ovmf, and swtpm for +tpm |
| Host tier | 1: production-ready |
| Byte order | little-endian (derived) |
All 61 cloud system names have an x86\_64 build, so NAME.x86_64 exists for every row of the support matrix, plus 13 Ubuntu Core systems.
| Boot | Systems |
|---|---|
| bios | amazonlinux-cloud-2, centos-cloud-9, centos-cloud-10, oracle-cloud-7, oracle-cloud-8, oracle-cloud-9 |
| efi | the other 55 cloud systems, and ubuntu-core-16, -18, -20, -22, -24, -26 and -22+dangerous, -24+dangerous, -26+dangerous |
| efi with Secure Boot and a TPM | ubuntu-core-24+tpm, -24+dangerous+tpm, -26+tpm, -26+dangerous+tpm |
Only on x86\_64: archlinux-cloud, oracle-cloud-7, ubuntu-cloud-16.10, 17.04, 17.10, 18.10, 19.04, 19.10, 20.10, 21.04, 21.10, 22.10, 23.04, 23.10, 24.10, ubuntu-core-16, -18, -20 and the four +tpm systems.
| Variable | Effect |
|---|---|
QEMU_ACCEL_MACHINE_PROP | replaces ,accel=kvm:tcg, such as ,accel=tcg |
QEMU_SMP_OPTION, QEMU_MEM_OPTION | replace -smp N and -m 2048 |
QEMU_BOOT_FIRMWARE_OPTION | replaces the two pflash drives of an efi system |
QEMU_CPU_X86_64 | make variable or environment: the -cpu model written into a new .run script, Haswell for EL 10 under TCG |
See the .run script for every run-time variable.
| Fact | Source |
|---|---|
| Program, machine, CPU, SMP, network | mk/010-qemu-x86_64.mk:3-11 |
| Accelerator test | mk/010-qemu-x86_64.mk:63 |
| Native vCPU count, memory | mk/010-qemu.mk:5-12 |
| Boot types allowed | rulegen.py:302-309 |
| OVMF lists and copies | mk/010-qemu-x86_64.mk:260-329 |
q35,smm=on for +tpm | mk/050-ubuntu-core.mk:55 |
| Snap component | snap/snapcraft.yaml:59-66, snap/hooks/install:6-13 |
| Container | Dockerfile:33, Dockerfile:78-102, .gitlab-ci.yml:1238-1276 |
| Host tier | README.md:384-396 |
| Make variable | Effect |
|---|---|
QEMU_SMP_X86_64 | the default -smp |
QEMU_SYSTEM_X86_64 (?=) | the QEMU program |
QEMU_EDK2_CODE_X86_64, QEMU_EDK2_VARS_X86_64 (?=) | the OVMF search lists |
QEMU_EDK2_SECBOOT_CODE_X86_64, QEMU_EDK2_SECBOOT_VARS_X86_64 (?=) | the Secure Boot search lists |
GARDEN_X86_64_PREFIX (environment) | appends a self-built QEMU's share/qemu firmware |
See six architectures for how the defaults are set.
image-garden make runs make -f PREFIX/include/image-garden.mk. The file is built by the top-level Makefile from mk/*.mk, data/*.ini and rulegen.py, and installed with make install.
GARDEN_INCLUDE=@INCLUDEDIR@, which make install fills in with $(includedir), and image-garden make runs make --warn-undefined-variables GARDEN_ITSELF=… GARDEN_PROJECT_DIR=… -f "$GARDEN_INCLUDE"/image-garden.mk -C DIR "$@" (image-garden:10-12, image-garden:982-993).all:: image-garden.mk; prefix defaults to /usr/local and includedir to $(prefix)/include (Makefile:6-21).mk/ holds 14 .mk files (and a README), data/ 13 INI files (and a README). The joined file had 15,889 lines when built in a scratch copy of the pinned commit: 847 of metadata, 1,907 written by hand and 13,135 generated.image-garden.mk" to /usr/local/include or /usr/include.make install replaces @PREFIX@, @INCLUDEDIR@ and @DOCDIR@ in the installed script (Makefile:33-38). Run from the source tree, the script still has the placeholder, notices it, and reads image-garden.mk from its own directory, the top of the tree (image-garden:13-19).cat data/000-systems.mk $(sort mk/*.mk) $(sort data/050-*.gen.mk) >image-garden.mk. Each rule file depends on its INI file and on rulegen.py; the metadata depends on all of them.
image-garden.mk: $(wildcard mk/*.mk) $(foreach n,$(wildcard data/*.ini),data/050-$(basename $(notdir $n)).gen.mk) data/000-systems.mk with the recipe cat data/000-systems.mk $(sort $(filter mk/%.mk,$^)) $(sort $(filter data/050-%.gen.mk,$^)) >$@, then touch --reference= the newest prerequisite, so the file gets the time of its newest part rather than the time it was joined (Makefile:48-50).data/050-%.gen.mk: rulegen.py data/%.ini (Makefile:57-58); data/000-systems.mk depends on every INI file and on rulegen.py (Makefile:60-64).make image-garden.mk printed in a scratch copy of the tag. The six per-architecture files are 010-qemu-aarch64, -loongarch64, -ppc64, -riscv64, -s390x and -x86_64.mk/999-local.mk is one line: -include $(GARDEN_PROJECT_DIR)/.image-garden.mk (999-local.mk:4-5).data/*.mk and image-garden.mk are in .gitignore:16-17; make clean removes all three kinds (Makefile:23-27).mk/050-* files..image-garden.mk.rulegen.py --systems-meta data/000-systems.mk writes _NAME_group, _group_upper, _release, _arch and _boot. define-instance in .image-garden.mk reads them before the generated rules are read.
data/000-systems.mk is removed, then built by running ./rulegen.py --systems-meta $@ $$f >/dev/null for each INI file in sorted order (Makefile:60-64). For each system rulegen.py appends _NAME_group, _NAME_group_upper, _NAME_release, _NAME_arch and _NAME_boot with := (rulegen.py:824-833). It is 847 lines for 139 systems.define-instance is used as $(eval $(call define-instance,BASE,NAME)); it tells a name with an architecture from one without by asking whether _BASE_group is defined, then reads the group, upper-case group, release, boot type and architecture of the base from these variables; the architecture picks the QEMU rules, so a base named .ppc64el gets the ppc64 ones (020-instances.mk:4-19, 020-instances.mk:29-56).GARDEN_SYSTEMS by 050-ubuntu-core.mk:4-16 but get no metadata. The README says so: instances can be made of the systems in data/*.ini, "which are all but Ubuntu Core"; define-instance with an Ubuntu Core system lists the instance in list-systems, but make has no rule for it (README.md:976-979, 020-instances.mk:9-10).$(sort) is byte order: 010-qemu-x86_64.mk before 010-qemu.mk, which sets the host architecture's SMP to 4; 050-ubuntu.mk after 010-qemu.mk, so its EXTRA_CLOUD_INIT_APT_CONFIG wins; 050.gentoo.mk after the 050- files.
mk/ files and the generated files with make's $(sort) (Makefile:48-50), which orders words lexically by byte; - is 0x2D and . is 0x2E. The order make image-garden.mk printed in a scratch copy of the pinned commit: 010-qemu-aarch64 … 010-qemu-x86_64, then 010-qemu.mk; 050-amazonlinux-2.mk, 050-ubuntu-core.mk, 050-ubuntu.mk, 050.gentoo.mk, 999-local.mk.QEMU_SMP_X86_64 = 1 (010-qemu-x86_64.mk:7-7); QEMU_SMP_$(shell echo $(GARDEN_HOST_ARCH) | tr a-z- A-Z_) = 4 (010-qemu.mk:5-6), where GARDEN_HOST_ARCH is uname -m with ppc64le mapped to ppc64 (000-garden.mk:16). Both are recursive (=) assignments; the last one read wins, and a project's .image-garden.mk, read later still, can set its own.EXTRA_CLOUD_INIT_APT_CONFIG = (010-qemu.mk:47-47), called by the base template (010-qemu.mk:198-198); redefined to call UBUNTU_OLD_RELEASES_APT_CONFIG in 050-ubuntu.mk:26-28. Were the files the other way round, the empty assignment would win and old Ubuntu releases would lose their apt block (derived).mk/050.gentoo.mk only defines GENTOO_CLOUD_INIT_USER_DATA_TEMPLATE (050.gentoo.mk:4-8), so its place in the order changes nothing.4 native, 1 cross-arch", which is what this order produces, a ppc64le host included (README.md:389-396, README.md:890-895).make install puts image-garden.mk in $(includedir) and writes the prefix into the script. The snap uses prefix=/usr and a layout for /usr/include/image-garden.mk; the container installs to /usr/local; an uninstalled script reads the file next to itself.
make install depends on image-garden.mk, installs the script to $(bindir) and runs sed on the installed copy to write in $(prefix), $(includedir) and $(datarootdir)/doc/image-garden, and installs image-garden.mk to $(includedir), by default /usr/local/include; a different includedir or datarootdir is honoured (Makefile:6-14, Makefile:29-46).GARDEN_INCLUDE=@INCLUDEDIR@; when the prefix is still the placeholder, GARDEN_INCLUDE becomes the script's own directory (image-garden:10-19).prefix=/usr to make (snapcraft.yaml:301-303), and its layout binds /usr/include/image-garden.mk to $SNAP/usr/include/image-garden.mk (snapcraft.yaml:250-252)./src/image-garden and runs make, make check and make install there (Dockerfile:69-71).image-garden.mk lists the mk/*.mk files, the generated rule files and the metadata as prerequisites, so make in the tree rebuilds it after an edit; an installed copy is replaced only by make install (derived).A failed ./rulegen.py data/gentoo.ini >data/050-gentoo.gen.mk leaves an empty file, and make deletes it: the top-level Makefile has .DELETE_ON_ERROR. Every later make fails the same way until the INI file is fixed.
Boot=uefi in the first section of data/gentoo.ini: make stopped with data/gentoo.ini: error: Image 'gentoo-cloud.x86_64' has Boot='uefi', use one of platform, efi, bios, then make: *** [Makefile:58: data/050-gentoo.gen.mk] Error 1 and make: *** Deleting file 'data/050-gentoo.gen.mk'. A second make printed the same three lines. After restoring Boot=efi, make built the rule file, data/000-systems.mk and image-garden.mk with Gentoo's systems.>$@ before rulegen.py runs (Makefile:57-58); the metadata recipe starts with rm -f $@ and appends file by file (Makefile:60-64). .DELETE_ON_ERROR in the top-level Makefile, "so that the next make does not use it", makes make delete either of them when its recipe fails (Makefile:16-18). image-garden.mk sets the same for the rules it runs at run time (000-garden.mk:4-7).FILE: error: MESSAGE without a traceback (rulegen.py:753-757).image-garden.mk already built from the earlier, good INI file is not touched by the failed run; it stays out of date, so the next make tries again (derived from the rule at Makefile:48-50).make clean removes image-garden.mk, data/050-*.gen.mk and data/000-systems.mk (Makefile:23-27); it is not needed after such an error.Next: rulegen.py, the hand-written rules, .image-garden.mk, the SMP default, image-garden make, and the source build.
cat data/000-systems.mk $(sort mk/*.mk) $(sort data/050-*.gen.mk) >image-garden.mk (Makefile:48-50).Read in the top-level Makefile, rulegen.py, mk/*.mk, mk/README.md, the image-garden script, snap/snapcraft.yaml, the Dockerfile and .gitignore of image-garden at the pinned commit ("code"). The order of the parts, the line counts and the runs after an error come from make image-garden.mk in a scratch copy of that commit ("run"). What would happen with another order, and when an installed copy is replaced, are reasoned from make's rules ("derived").
| # | File | Lines | What it holds |
|---|---|---|---|
| 1 | data/000-systems.mk | 847 | five variables per system from the INI files |
| 2 | mk/000-garden.mk | 87 | .DELETE_ON_ERROR, cache directories, CURL, XORRISO, log banners, GARDEN_SYMLINK, help, list-systems |
| 3 | mk/010-qemu-aarch64.mk | 218 | QEMU command lines, run scripts and firmware for aarch64 |
| 4 | mk/010-qemu-loongarch64.mk | 119 | the same for loongarch64 |
| 5 | mk/010-qemu-ppc64.mk | 72 | the same for ppc64 |
| 6 | mk/010-qemu-riscv64.mk | 121 | the same for riscv64 |
| 7 | mk/010-qemu-s390x.mk | 72 | the same for s390x |
| 8 | mk/010-qemu-x86_64.mk | 334 | the same for x86_64, with Secure Boot and swtpm |
| 9 | mk/010-qemu.mk | 347 | common QEMU settings, pkgproxy, the cloud-init templates and picker, the seed ISO, the locked unpack and convert |
| 10 | mk/020-instances.mk | 157 | define-instance |
| 11 | mk/050-amazonlinux-2.mk | 11 | Amazon Linux 2's template and the aarch64 CPU |
| 12 | mk/050-ubuntu-core.mk | 328 | every Ubuntu Core system |
| 13 | mk/050-ubuntu.mk | 28 | the apt block for old Ubuntu releases |
| 14 | mk/050.gentoo.mk | 8 | Gentoo's template |
| 15 | mk/999-local.mk | 5 | -include $(GARDEN_PROJECT_DIR)/.image-garden.mk |
| 16-28 | data/050-almalinux.gen.mk … data/050-ubuntu.gen.mk | 13,135 | the generated rules, one file per INI file |
Total: 15,889 lines. The mk/ files are sorted with make's $(sort), byte by byte, so 010-qemu-*.mk precede 010-qemu.mk and 050.gentoo.mk follows the 050- files (Makefile:48-50).
| Target | What it does |
|---|---|
all (default) | builds image-garden.mk |
install | installs image-garden, image-garden.mk, the manual page and the documentation under DESTDIR and prefix (or bindir, includedir, datarootdir, man1dir), and writes the prefix, the include directory and the documentation directory into the script |
clean | removes image-garden.mk, data/050-*.gen.mk and data/000-systems.mk |
check | check-sh, check-py, check-rulegen, check-dl-pkgproxy, check-allocate, check-rebase, check-dl-unpack-lock, check-pkgproxy-guest-shell |
fmt | shfmt and black |
dist | image-garden-VERSION.tar.gz with the sources, not the generated files |
Source: Makefile:16-141.
| Install | Prefix | image-garden.mk | Source |
|---|---|---|---|
make install | /usr/local, or prefix= | $(includedir)/image-garden.mk, by default PREFIX/include | Makefile:6-46 |
| the snap | /usr | /usr/include/image-garden.mk, bound by a layout | snapcraft.yaml:250-252, :301-303 |
| the container | /usr/local | /usr/local/include/image-garden.mk | Dockerfile:69-71 |
| not installed | none | image-garden.mk next to the script | image-garden:13-19 |
A failed rulegen.py run leaves an empty data/050-X.gen.mk, and a failed metadata loop a partial data/000-systems.mk; the top-level Makefile has .DELETE_ON_ERROR, so make deletes the file and prints make: *** Deleting file '…' (Makefile:16-18). Every later make fails the same way until the INI file is fixed (run); make clean is not needed.
A section without SHA256SUMS, SHA512SUMS or SHA256SUM stops the build: defines no checksum, use one of SHA256SUMS=, SHA512SUMS= or SHA256SUM=.
Checksums(SHA256SUMS=…, SHA256SUM=…, SHA512SUMS=…); when all three are empty, "Image {name} defines no checksum, use one of SHA256SUMS=, SHA512SUMS= or SHA256SUM=" (rulegen.py:420-431), prefixed with FILE: error: (rulegen.py:753-757). The message on the slide was produced by running rulegen.py at the pinned commit; it is one line, with no traceback.rulegen.py fails on an image section without a checksum" (data/README.md:47-51).SHA256SUMS=https://cloud-images.ubuntu.com/noble/current/SHA256SUMS (data/ubuntu.ini:237-242).download helper without a checksum (image-garden:627-660), but no rule that rulegen.py writes uses it (rulegen.py:498-517).tests/check-rulegen.sh holds this in place (tests/check-rulegen.sh:96-98).SHA256SUMS and SHA512SUMS are URLs fetched with the image, so they follow it. SHA256SUM is a literal hash that pins one file, as Oracle Linux does.
SHA256SUMS in 118 sections, SHA512SUMS in 14 (Debian 12, Alpine 2), SHA256SUM in Oracle Linux's 7 (counted at the tag), for example data/oracle.ini:10-15, data/debian.ini:10-16 and data/alpine.ini:8-13.SHA512SUMS is the .sha512 file beside each image, holding a bare hash, a format the helper accepts when it is the only non-empty line (data/README.md:59-61, image-garden:75-92).SHA256SUM the hash comes from the data, and a mismatch deletes the image only and tries once more (image-garden:582-625).…/noble/current/, which Ubuntu updates in place (derived from the path); Debian's into …/daily/latest/ (data/debian.ini:10-16). That a vendor may replace the file behind a fixed URL, so a literal hash stops matching, is derived.SHA256SUMS=@URL@.sha256 becomes the resolved image URL plus .sha256, read from SYSTEM.url when the download runs. Only at the start, once, and only in SHA256SUMS or SHA512SUMS.
URL_PLACEHOLDER = "@URL@", allowed in SHA256SUMS and SHA512SUMS; expand_url_placeholder replaces it with $$(cat $(word 1,$^)), the .url file that is the download rule's first prerequisite (rulegen.py:51-88). The .url file holds the URL that URL gives or URLProgram prints (rulegen.py:520-530).validate_url_placeholder: in any other key, "uses @URL@ in 'KEY', it is only allowed in SHA256SUMS= and SHA512SUMS="; not at the start, or more than once, "must use @URL@ once, at the start of the value, e.g. @URL@.sha256" (rulegen.py:91-111). The key in the first message is lower-case, as the INI reader stores it.URLProgram and SHA256SUMS=@URL@.sha256 (data/gentoo.ini:8-14). OpenCloudOS uses the placeholder with a fixed URL (data/opencloudos.ini:13-16).LocalFilenameTemplate, so its .sha256 file is matched by the basename (derived).The download rule picks SHA512SUMS, else SHA256SUM, else SHA256SUMS. Any other key is ignored without a warning.
ifneq (,SHA512SUMS) → download-with-sha512sums, else ifneq (,SHA256SUM) → download-with-sha256sum, else ifneq (,SHA256SUMS) → download-with-sha256sums (rulegen.py:498-517). rulegen.py checks only that at least one is set (rulegen.py:420-431).data/*.ini at the tag has exactly one checksum key (counted).tests/check-rulegen.sh: @URL@ expands in both list keys, is refused in SHA256SUM, elsewhere in the value or twice, and a section without a checksum is refused.
write_ini NAME FIELD… writes [META] Group=test Variant=cloud and one [test-cloud.x86_64] section with Arch=x86_64 and Boot=efi (tests/check-rulegen.sh:18-28).url-placeholder-sha256sums and url-placeholder-sha512sums expect $$(cat $(word 1,$^)).sha256 and .sha512 in the download command; url-placeholder-in-sha256sum, url-placeholder-not-at-start, url-placeholder-twice expect the two placeholder errors; no-checksum expects "error: Image 'test-cloud.x86_64' defines no checksum" (tests/check-rulegen.sh:76-98). Every error case also fails if rulegen.py prints a Python traceback (:65-72). The same file also checks loongarch64 (:100-109), the local file name keys and clashes between file names (:111-170), and the [META], Arch and Boot keys (:172-223).make check-rulegen runs it (Makefile:99-100); make check includes it, and the container build runs make check (Dockerfile:71).Next: downloading and checking, the other INI keys, URLProgram, and image downloads through pkgproxy.
Read in rulegen.py, data/*.ini, data/README.md, tests/check-rulegen.sh and the image-garden script at the pinned commit ("code"); the counts were taken from the section headers and keys there. The error messages were produced by running that rulegen.py ("run").
| Key | Value | Helper | Used by |
|---|---|---|---|
SHA256SUMS | URL of a SHA-256 list, or of one bare hash; may start with @URL@ | download-with-sha256sums | 118 sections: AlmaLinux, Amazon Linux, Arch Linux, CentOS, Fedora, Gentoo, OpenCloudOS, openSUSE, Rocky, Ubuntu |
SHA512SUMS | URL of a SHA-512 list, or of one bare hash; may start with @URL@ | download-with-sha512sums | 14 sections: Debian, Alpine |
SHA256SUM | the SHA-256 hash itself | download-with-sha256sum | 7 sections: Oracle Linux |
With more than one key, the first of SHA512SUMS, SHA256SUM, SHA256SUMS is used (rulegen.py:498-517).
| Format | Example line |
|---|---|
GNU, as sha256sum prints it | HASH NAME or HASH *NAME |
BSD, as sha256sum --tag prints it | SHA256 (NAME) = HASH |
| one bare hash | HASH, the only non-empty line, of the right length |
The name looked up is the saved file name, else the URL's basename (image-garden:75-92, :508-515). More in downloading and checking images.
| Value | Result |
|---|---|
SHA256SUMS=@URL@.sha256 | the URL in SYSTEM.url followed by .sha256, read when the download runs |
SHA512SUMS=@URL@.sha512 | the same with .sha512 |
SHA256SUM=@URL@ | refused: only allowed in SHA256SUMS= and SHA512SUMS= |
SHA256SUMS=http://example.org/@URL@ | refused: once, at the start |
SHA256SUMS=@URL@@URL@ | refused: once, at the start |
Sources: rulegen.py:51-111, tests/check-rulegen.sh:79-94.
mk/050-ubuntu-core.mk defines nineteen Ubuntu Core systems on its own. mk/050-amazonlinux-2.mk, mk/050.gentoo.mk and mk/050-ubuntu.mk adjust generated systems.
mk/050-ubuntu-core.mk (324 lines at the tag) adds ubuntu-core-R.x86_64 for 16, 18, 20, 22, 22+dangerous, 24, 24+dangerous, 26 and 26+dangerous, the same from 22 on for aarch64, and four +tpm systems on x86_64: nineteen in all (050-ubuntu-core.mk:4-16).mk/050-amazonlinux-2.mk: AMAZONLINUX_2_CLOUD_INIT_USER_DATA_TEMPLATE, which adds shutdown --poweroff now, and QEMU_CPU_AARCH64=neoverse-n1 for Amazon Linux's aarch64 systems (050-amazonlinux-2.mk:4-11). The CPU line names the 2023 systems too.mk/050.gentoo.mk: GENTOO_CLOUD_INIT_USER_DATA_TEMPLATE, which adds systemctl enable --now sshd.service (050.gentoo.mk:4-8).mk/050-ubuntu.mk: UBUNTU_OLD_RELEASES_VERSIONS, 16.10 to 24.10, and the apt block for old-releases.ubuntu.com through EXTRA_CLOUD_INIT_APT_CONFIG (050-ubuntu.mk:4-28).mk/ files are machinery shared by every system (QEMU, templates, instances); this deck is about the four that name particular systems.GARDEN_SYSTEMS, all::, fetch, meta-data, user-data, the verified download, the cache link, .qcow2, .run and clean::: Ubuntu Core writes them as static pattern rules over UBUNTU_CORE_RELEASES.
GARDEN_SYSTEMS, all::, meta-data, user-data and clean:: (rulegen.py:452-478); fetch, distclean:: and the verified download with its link (rulegen.py:480-518); .run and .qcow2 (rulegen.py:593-610).GARDEN_SYSTEMS (050-ubuntu-core.mk:4-16); .run and .qcow2 as static pattern rules, $(foreach R,…): ubuntu-core-%.x86_64.run: … (050-ubuntu-core.mk:23-53); meta-data and user-data (050-ubuntu-core.mk:111-129); all:: and fetch, on x86_64 and aarch64 only (050-ubuntu-core.mk:186-197); one download rule per release and channel, and one link per system (050-ubuntu-core.mk:199-308); .PRECIOUS, clean:: and distclean:: (050-ubuntu-core.mk:310-328).%.qcow2: %.img.xz in 010-qemu.mk:340-347 turns ubuntu-core-24-amd64.img.xz into ubuntu-core-24-amd64.qcow2, which the link points at.$(GARDEN_ITSELF) download-with-sha256sums, with SHA256SUMS from the same directory on cdimage.ubuntu.com.ubuntu-core-16, 18 and 20 have no aarch64 rules; the +tpm systems have rules of their own, covered in Secure Boot and a TPM.Unpacking and converting .img.xz, a group that is not the user, a SCSI CD-ROM seed, its own template, and modifiers that share a download: none of these is a key in data/*.ini.
ubuntu-core-R-ARCH.img.xz; %.qcow2: %.img.xz unpacks and converts them under a lock (010-qemu.mk:340-347). The generated download rule links the downloaded file itself (rulegen.py:510-514).--query's (rulegen.py:467-467, rulegen.py:596-596); Ubuntu Core passes ubuntu-core as the group and ubuntu as the user, and only:ubuntu to --query (050-ubuntu-core.mk:25-25, 050-ubuntu-core.mk:116-116).-device virtio-blk (rulegen.py:604-609); Ubuntu Core: -device virtio-scsi-pci,id=scsi1 -device scsi-cd,drive=drive1,bus=scsi1.0 (050-ubuntu-core.mk:37-53).BASE_UBUNTU_CORE_CLOUD_INIT_USER_DATA_TEMPLATE, picked through the key UBUNTU_CORE (050-ubuntu-core.mk:131-179). A generated system could get a group template too; the other four points are what rule it out.+dangerous downloads from dangerous-stable (050-ubuntu-core.mk:223-251); a +tpm system links to the image of the system without it, after check-swtpm-component (050-ubuntu-core.mk:280-290), and its first boot starts swtpm (050-ubuntu-core.mk:78-106).A target-specific QEMU_CPU_AARCH64=neoverse-n1; templates named AMAZONLINUX_2_CLOUD_INIT_USER_DATA_TEMPLATE and GENTOO_CLOUD_INIT_USER_DATA_TEMPLATE; a redefined EXTRA_CLOUD_INIT_APT_CONFIG. The same works in .image-garden.mk.
amazonlinux-cloud-2.aarch64.qcow2 amazonlinux-cloud-2.aarch64.run amazonlinux-cloud-2023.aarch64.qcow2 amazonlinux-cloud-2023.aarch64.run : QEMU_CPU_AARCH64=neoverse-n1 (050-amazonlinux-2.mk:10-11); the default is max and the command line and the launcher read it (010-qemu-aarch64.mk:5-5, :14-14, :62-62). A target-specific value applies to that target's recipe and its prerequisites.GROUP_RELEASE@INSTANCE, GROUP@INSTANCE, GROUP_RELEASE, GROUP, then the common template (010-qemu.mk:293-298). AMAZONLINUX_2_… is a group-and-release name; Gentoo has no release, so GENTOO_… is the group name (050-amazonlinux-2.mk:4-8, 050.gentoo.mk:4-8).EXTRA_CLOUD_INIT_APT_CONFIG = is empty in 010-qemu.mk:47-47 and called with the group and release by the base template (010-qemu.mk:198-198); 050-ubuntu.mk:12-28 redefines it to emit an apt block for ubuntu releases in UBUNTU_OLD_RELEASES_VERSIONS..image-garden.mk replaces these, because its file is read later (what differs per distribution shows what to keep).BASE_CLOUD_INIT_USER_DATA_TEMPLATE, not CLOUD_INIT_USER_DATA_TEMPLATE, so a project that redefines the common template does not change these two systems. This may be intended.Hand-written rules get no rulegen.py checks, keep their own lists, repeat what the generator writes (set -o pipefail, all::, fetch, distclean::), so a fix has to be made twice, and have no entry in data/000-systems.mk.
+tpm on other architectures (050-ubuntu-core.mk:20-21).UBUNTU_OLD_RELEASES_VERSIONS and its comment, "Keep this list in sync with EOL ubuntu-cloud entries in data/ubuntu.ini." (050-ubuntu.mk:4-12). Ubuntu Core's releases are listed in UBUNTU_CORE_RELEASES and again in each download and link rule (050-ubuntu-core.mk:4-7, :199-308).set -o pipefail && … | tee (rulegen.py:606); Ubuntu Core's .qcow2 rules write the same again, with SHELL = bash (050-ubuntu-core.mk:37-53). Its all:: and fetch lines, limited to x86_64 and aarch64 (050-ubuntu-core.mk:186-197), and its distclean::, which removes the .img.xz downloads and the converted .qcow2 (050-ubuntu-core.mk:326-328), stand in for the generated fetch and distclean:: (rulegen.py:480-492). A change to one does not reach the other (derived).data/000-systems.mk is written from the INI files only (rulegen.py:824-833), and define-instance reads the base's group, release, boot type and architecture from it (020-instances.mk:29-56). Its comment and the README say so: instances are made of the systems in data/*.ini, "which excludes Ubuntu Core"; define-instance with an Ubuntu Core system lists the instance in list-systems, but make has no rule for it (020-instances.mk:4-10, README.md:976-979). Run in a scratch tree with $(eval $(call define-instance,ubuntu-core-24.x86_64,web)), make said "No rule to make target" for its .run..image-garden.mk (derived).Next: Ubuntu Core, the per-distribution quirks, how image-garden.mk is assembled, rulegen.py, Secure Boot and the TPM, and named instances.
mk/050-ubuntu-core.mk, mk/050-amazonlinux-2.mk, mk/050.gentoo.mk and mk/050-ubuntu.mk.data/*.ini: thirteen files, a [META] section and one section per system. [ubuntu-cloud-24.04.x86_64] has URL, SHA256SUMS, Arch, Boot and Release.
[META].[META] in ubuntu.ini: Group=ubuntu, Variant=cloud (data/ubuntu.ini:4-6). The running example: URL, SHA256SUMS, Arch=x86_64, Boot=efi, Release=24.04 (data/ubuntu.ini:237-242).rulegen.py reads [META] and then every other section as one system named after the section (rulegen.py:336-351); the build runs it once per file (Makefile:57-58).mk/050-ubuntu-core.mk, not from an INI file; see rules written by hand.; are comments, as in the SPDX header of each file.Group=ubuntu picks the download directory, the user, the template prefix and the host name. Variant=cloud is required but not used by any rule; without either, rulegen.py says [META] has no Group=.
required, which fails on a missing or empty value (rulegen.py:280-285, rulegen.py:343-348). A file without [META] stops with data/X.ini: error: no [META] section, one without a key with data/X.ini: error: [META] has no Group= or [META] has no Variant= (run; also checked by tests/check-rulegen.sh:172-181).$(GARDEN_DL_DIR)/GROUP (rulegen.py:447-450), the second user and the upper-case template prefix (rulegen.py:467), and with the release the guest's host name, dots and pluses turned into dashes (mk/010-qemu.mk:97, mk/010-qemu.mk:196). The user is named after the group with the group as its password (mk/010-qemu.mk:205-208).Group.variant is used only by Group.full, which nothing calls (rulegen.py:32-48).Name contains Arch; exactly one of URL and URLProgram; at least one checksum key; Boot that the architecture has rules for; Release.
Arch is required and must be one of x86_64, aarch64, riscv64, s390x, ppc64, loongarch64 (rulegen.py:23-29, rulegen.py:396-401), and the section name must contain it, else "Suspicious image" (rulegen.py:402-405).URL must contain the architecture; amd64 is accepted for x86_64 and arm64 for aarch64, else "Suspicious URL" (rulegen.py:406-416).URL and URLProgram (rulegen.py:357-362); LocalFilename goes only with URL, URLPattern and LocalFilenameTemplate only with URLProgram, as a pair (rulegen.py:364-393). Gentoo's sections show the URLProgram form (data/gentoo.ini:8-14); see URLProgram.SHA256SUMS, SHA512SUMS, SHA256SUM (rulegen.py:420-431); see checksums.Boot is checked against the architecture: efi or bios on x86_64, efi on aarch64, riscv64 and loongarch64; s390x and ppc64 boot with the machine's own firmware, platform, which is their default and their only value (rulegen.py:300-333, rulegen.py:440). The ubuntu.ini ppc64el and s390x sections have no Boot. Release defaults to empty, as in Gentoo and Arch Linux (rulegen.py:441). The release goes into the host name and the template names (rulegen.py:461-467).[META] keys and Arch, Boot, Release, URL and URLProgram (data/README.md:15-45), then the checksum and file-name keys.No [DEFAULT], no inheritance: every section repeats every key. [ubuntu-cloud-24.04.ppc64el] has Arch=ppc64, which its name contains.
SHA256SUMS, Boot and Release; the name, the URL and Arch differ.data/ has a [DEFAULT] section (searched at the tag). rulegen.py walks the sections and reads each key from the section itself (rulegen.py:336-355). Python's INI reader would hand the keys of a [DEFAULT] section to every section, [META] included (derived, not tried).[ubuntu-cloud-14.04.ppc64el] has Arch=ppc64 and no Boot (data/ubuntu.ini:24-27); the check is a substring test (rulegen.py:402-405). The system's name, its .run script and its files all say ppc64el.data/X.ini: error: Suspicious URL … for architecture x86_64, … defines no checksum …, … has no Boot=, use efi or bios for x86_64. make then deletes the unfinished data/050-X.gen.mk.
rulegen.py at the pinned commit on a one-section file (Python 3.14). main turns a ValueError from reading a file into SystemExit(f"{filename}: error: {exc}"), so it prints one line and no traceback (rulegen.py:753-757). Unreadable files and INI syntax errors, such as a section or key given twice, are reported the same way (rulegen.py:338-342).URL and URLProgram (rulegen.py:358-363); suspicious image and URL (rulegen.py:402-416); no checksum (rulegen.py:426-431).Arch gives Image 'S' has no Arch=; an unknown one Image 'S' has Arch='x86-64', use one of x86_64, aarch64, riscv64, s390x, ppc64, loongarch64 (rulegen.py:280-297, rulegen.py:396-401).Boot is checked against the architecture (rulegen.py:300-333): Image 'S' has no Boot=, use efi or bios for x86_64 (or use efi for aarch64), Image 'S' has Boot='uefi', use one of platform, efi, bios, and Image 'S' has Boot=bios, which aarch64 does not support, use efi. On s390x and ppc64 a missing Boot means platform. See when Boot is wrong or missing.data/X.ini: error: per-group local filename collision in group 'G': 'F' used by 'S1' and 'S2' (rulegen.py:758-775)../rulegen.py data/X.ini >data/050-X.gen.mk (Makefile:57-58). The shell creates the output before rulegen.py fails; the top-level Makefile has .DELETE_ON_ERROR (Makefile:16-18), so make deletes it (run: make: *** Deleting file 'data/050-example.gen.mk'). The next make runs rulegen.py again.tests/check-rulegen.sh checks these messages, and that none of them comes with a traceback (tests/check-rulegen.sh:65-72, tests/check-rulegen.sh:96-223)../rulegen.py data/X.ini, then make, ./image-garden make list-systems and ./image-garden make SYSTEM.run, all from the tree. make check-rulegen runs tests/check-rulegen.sh.
rulegen.py takes INI files as arguments and prints the rules on standard output (rulegen.py:741-775).make rebuilds data/050-X.gen.mk for a changed data/X.ini, data/000-systems.mk from every file, and joins image-garden.mk (Makefile:48-64).image-garden still has @PREFIX@ in it and then looks for image-garden.mk next to itself (image-garden:10-19); see installing from source.list-systems prints GARDEN_SYSTEMS, to which every section adds itself (mk/000-garden.mk:85-87, rulegen.py:453-454).make check-rulegen runs tests/check-rulegen.sh (Makefile:99-100), which prints PASS: NAME or FAIL: NAME for each case (tests/check-rulegen.sh:30-74). make check also runs shellcheck and mypy, see installing from source.| less and | grep on the slide are only for reading the output.Next: checksums, URLProgram, boot types, what rulegen.py emits and how image-garden.mk is put together.
[META] keys, the keys of an image section, checksums and file names.Read in rulegen.py, data/*.ini, data/README.md, the Makefile and tests/check-rulegen.sh at the pinned commit ("code"). The error messages were produced by running that rulegen.py on one-section files with Python 3.14, and make's on a failing build ("run"). What Python's INI reader would do with keys the files do not use is "derived".
| Key | Required | Example | Used for |
|---|---|---|---|
Group | yes | ubuntu | download directory $(GARDEN_DL_DIR)/GROUP, the second user and its password, the template prefix GROUP_…, the host name |
Variant | yes | cloud | nothing yet; every section name repeats it |
| Key | Required | Rule | Notes |
|---|---|---|---|
| section name | must contain Arch | becomes the system name, GROUP-VARIANT-RELEASE.ARCH by convention | |
Arch | yes | x86_64, aarch64, riscv64, s390x, ppc64, loongarch64 | the name must contain it |
URL | one of the two | must contain the architecture (amd64, arm64 accepted) | its basename is the cached file name |
URLProgram | one of the two | a shell command, run by make, that prints the URL | see URLProgram |
LocalFilename | no | only with URL; no /, not . or .. | overrides the cached file name |
URLPattern, LocalFilenameTemplate | no | only with URLProgram, together; one capture group, @1 | a stable cached file name |
SHA256SUMS, SHA512SUMS, SHA256SUM | at least one | lists by URL, or one hash; @URL@ only at the start of the first two | see checksums |
Boot | yes, except on s390x and ppc64 | efi or bios on x86_64; efi on aarch64, riscv64, loongarch64; platform (the default) on s390x and ppc64 | see boot types |
Release | no | any text, default empty | host name and per-release templates |
Sources: rulegen.py:17-29, rulegen.py:300-333, rulegen.py:336-445, data/README.md:15-88.
Every message is one line on standard error, data/X.ini: error: and then the text below; there is no traceback (rulegen.py:753-775). make then deletes the empty data/050-X.gen.mk (.DELETE_ON_ERROR, Makefile:16-18).
| Mistake | Message after data/X.ini: error: |
|---|---|
no [META] section | no [META] section |
no Group or Variant in [META] | [META] has no Group= or [META] has no Variant= |
| a section or key given twice, unreadable file | the INI reader's or the system's message, as in While reading from 'data/X.ini' [line 3]: option 'group' in section 'META' already exists |
both URL and URLProgram | Image 'S' defines both URL and URLProgram |
| neither | Image 'S' defines neither URL nor URLProgram |
no Arch | Image 'S' has no Arch= |
unknown Arch | Image 'S' has Arch='x86-64', use one of x86_64, aarch64, riscv64, s390x, ppc64, loongarch64 |
name without Arch | Suspicious image 'S' for architecture A |
| URL without the architecture | Suspicious URL 'U' for architecture A |
| no checksum | Image 'S' defines no checksum, use one of SHA256SUMS=, SHA512SUMS= or SHA256SUM= |
no Boot where one is needed | Image 'S' has no Boot=, use efi or bios for x86_64 (use efi for aarch64, and so on) |
unknown Boot | Image 'S' has Boot='uefi', use one of platform, efi, bios |
a Boot the architecture lacks | Image 'S' has Boot=bios, which aarch64 does not support, use efi |
@URL@ in another key | Image 'S' uses @URL@ in 'sha256sum', it is only allowed in SHA256SUMS= and SHA512SUMS= |
@URL@ not at the start, or twice | Image 'S' SHA256SUMS= must use @URL@ once, at the start of the value, e.g. @URL@.sha256 |
| two sections, one cached file name | per-group local filename collision in group 'G': 'F' used by 'S1' and 'S2' |
URL and Arch (or the release)../rulegen.py data/X.ini and read the rules for the new name.make, then ./image-garden make list-systems and ./image-garden make NAME.run from the tree.make check-rulegen, and make check before sending the change.At build time the Makefile runs ./rulegen.py data/ubuntu.ini >data/050-ubuntu.gen.mk. The five-line section of ubuntu-cloud-24.04.x86_64 becomes 93 lines of rules; all 139 systems give about 13,000.
[ubuntu-cloud-24.04.x86_64] (ubuntu.ini:237-242).data/050-%.gen.mk: rulegen.py data/%.ini runs ./rulegen.py data/X.ini >data/050-X.gen.mk (Makefile:57-58). rulegen.py accepts several files and prints to standard output (rulegen.py:741-757).GARDEN_SYSTEMS += line to the next system's; 13,135 lines in the thirteen data/050-*.gen.mk files for 139 systems; 5,224 of them in 050-ubuntu.gen.mk.data/*.mk and image-garden.mk are in .gitignore (.gitignore:16-17). A checkout's copies may be older than the INI files; read rulegen.py and the INI files, or build them again.Every section is read and checked before anything is printed: data/X.ini: error: … names the file and the section. Then the cached file names are compared. A file with a mistake gives no rules at all.
load_images reads the file and checks each section in this order: URL against URLProgram, the file-name keys, Arch (an architecture rulegen.py knows, contained in the section name), the architecture in the URL, the @URL@ placeholder, a checksum, then Boot, which must be one the architecture has rules for (rulegen.py:336-445, rulegen.py:300-333). Missing [META], Group, Variant or Arch are reported the same way, as are INI syntax errors (rulegen.py:280-297, rulegen.py:338-348). The architectures and boot types are the enums at rulegen.py:17-29.main turns the generator into a list first, so every section is checked before any output; a ValueError becomes SystemExit("FILE: error: MESSAGE"), exit status 1 (rulegen.py:753-757). The message on the slide is the one for a section without a checksum, as tests/check-rulegen.sh expects it.data/X.ini: error: per-group local filename collision in group 'G': 'NAME' used by 'A' and 'B' (run on a two-section test file).Per file: a header and the group's download directory. Per system: the common block, the fetch block, the .url and .filename rules, and the boot block, chosen by Arch and Boot.
main prints ruleset_header, then for the first system ruleset_group, and for every system ruleset_common, ruleset_fetch_common, the .url rule (ruleset_fetch_direct or ruleset_fetch_prog), the .filename rule (ruleset_filename_static, _dynamic_basename or _dynamic_pattern) and the boot ruleset; ruleset_footer ends the file (rulegen.py:777-822).GARDEN_SYSTEMS += NAME, which list-systems prints; all:: NAME.qcow2 NAME.run inside ifeq ($(GARDEN_ARCH),ARCH); NAME.meta-data and NAME.user-data from the templates, with the group, the upper-case group and the release; clean:: lines for the link, the disk, the launcher and the cloud-init files. The meta-data template gets the group and the release, so its local-hostname matches the user-data hostname.fetch: for the host's architecture, distclean:: (the download, the link, .url and .filename), .PRECIOUS for the link, and the rule for $(GARDEN_DL_DIR)/GROUP/NAME.qcow2, which runs download-with-sha512sums, -sha256sum or -sha256sums and makes the link. All three are written inside nested ifneq tests on the checksum keys, so make keeps the first one that is set.NAME.run and NAME.qcow2; which ruleset a system gets is in Architecture first, then boot type. Every combination rulegen.py accepts has a ruleset.[META] group (rulegen.py:778-780).Boot that has a boot block: rulegen.py refuses a missing or unsupported one, so no system gets all:: for a .qcow2 without a rule to make it (rulegen.py:300-333).Generated recipes call macros: EMIT_QEMU_RUN_SCRIPT_QUERY_PREAMBLE, EMIT_QEMU_SYSTEM_X86_64_EFI_RUN_COMMAND, QEMU_SYSTEM_X86_64_EFI_CMDLINE, PICK_CLOUD_INIT_USER_DATA_TEMPLATE_FOR, and image-garden download-with-sha256sums. How a system boots is changed in mk/.
.run recipe calls EMIT_QEMU_RUN_SCRIPT_QUERY_PREAMBLE and EMIT_QEMU_SYSTEM_X86_64_EFI_RUN_COMMAND; the .qcow2 recipe runs $(QEMU_IMG) create and QEMU_SYSTEM_X86_64_EFI_CMDLINE with the seed attached (rulegen.py:593-610).EMIT_QEMU_RUN_SCRIPT_QUERY_PREAMBLE (010-qemu.mk:57-57), CLOUD_INIT_META_DATA_TEMPLATE (010-qemu.mk:97-106), PICK_CLOUD_INIT_USER_DATA_TEMPLATE_FOR (010-qemu.mk:293-298), QEMU_SYSTEM_X86_64_EFI_CMDLINE (010-qemu-x86_64.mk:13-13) and EMIT_QEMU_SYSTEM_X86_64_EFI_RUN_COMMAND (010-qemu-x86_64.mk:49-49). Each architecture has its own mk/010-qemu-ARCH.mk with the same set.$(GARDEN_ITSELF) is the path of the image-garden script, which image-garden make passes to make; download-with-sha256sums is one of its commands (rulegen.py:510-514, image-garden:460-473).mk/ reaches every generated system without running rulegen.py again; image-garden.mk still has to be rebuilt from the parts (how image-garden.mk is put together).ifeq on GARDEN_ARCH, the .url and .filename recipes.Rulesets are str.format templates: {img.name} is a field, {{ and }} are braces, $$ is a dollar for the shell. Recipe lines start with + under .RECIPEPREFIX=+, which the footer resets.
.format(img=img) or .format(group=…), so {img.name}, {img.group}, {img.arch} and the properties of Image are fields (rulegen.py:777-822)..filename rule is written awk 'BEGIN {{ … }}', and "$${{META_DATA}}" becomes "$${META_DATA}" in the rule file and "${META_DATA}" for the shell (rulegen.py:460-471, rulegen.py:546-591).$$ is make's escape for one $; $@, $<, $^ and $(…) are left single on purpose, for make. The row on the slide is from the .filename rule for a URLProgram without a pattern (rulegen.py:538-544); the +mkdir -p $@ row is the group directory rule (rulegen.py:447-450).LocalFilename, URLPattern, LocalFilenameTemplate) go through shlex.quote and have every $ doubled (rulegen.py:138-158). URL and URLProgram are pasted as they are, so they are written in make syntax in the INI file..RECIPEPREFIX=+; the footer: "Reset rules to use tabs." .RECIPEPREFIX= (rulegen.py:726-738). A continuation line of a recipe, such as the -drive lines of the provisioning boot, starts with spaces..RECIPEPREFIX needs GNU make 3.82 or later (derived, from GNU make's documentation).make check-py runs mypy --strict; make check-rulegen runs tests/check-rulegen.sh, whose cases expect a fragment of the output or of the error. Comparing data/050-*.gen.mk before and after shows what the change did to each distribution.
check-py runs mypy --strict on rulegen.py and three Python test helpers; check-rulegen runs tests/check-rulegen.sh; both are part of make check (Makefile:66-67, Makefile:88-100). Run in a scratch copy of the pinned commit, both passed: "Success: no issues found in 4 source files" and 38 PASS lines.write_ini NAME FIELD… writes [META] Group=test Variant=cloud and one [test-cloud.x86_64] section with Arch=x86_64, Boot=efi and the given fields; expect_ok NAME [PATTERN] wants rulegen.py to succeed with PATTERN, a fixed string, in its output; expect_error NAME PATTERN wants it to fail with PATTERN in the error and no Python traceback (tests/check-rulegen.sh:18-74).@URL@, a missing checksum, loongarch64, LocalFilename, URLPattern and LocalFilenameTemplate, the file-name clash, the [META] keys, Arch, Boot per architecture, a duplicate section and a missing file (tests/check-rulegen.sh:76-223).data/050-*.gen.mk aside, rebuild with make image-garden.mk, and diff the files. The file name on the slide is an example.make check need more tools: shellcheck, the pkgproxy download tests, the allocate test, the rebase test and the unpack-lock test (Makefile:66-115).Next: boot types, the target chain, how image-garden.mk is assembled, and the INI, checksum and URLProgram keys.
Read in rulegen.py, the Makefile, tests/check-rulegen.sh, mk/010-qemu.mk and mk/010-qemu-x86_64.mk of image-garden at the pinned commit ("code"). The line counts, the error messages and the test results come from running make image-garden.mk, make check-py, make check-rulegen and rulegen.py on small INI files in a scratch copy of that commit ("run"). Advice on comparing rule files, and the GNU make version for .RECIPEPREFIX, are not in the source ("derived").
./rulegen.py [--systems-meta FILE] FILE.ini...
| Argument | Effect |
|---|---|
FILE.ini... | checked one after the other; the rules of each are printed to standard output |
--systems-meta FILE | also appends five variables per system to FILE; see how image-garden.mk is put together |
The Makefile runs ./rulegen.py data/X.ini >data/050-X.gen.mk for each INI file, and ./rulegen.py --systems-meta data/000-systems.mk data/X.ini >/dev/null for each to build the metadata (Makefile:57-64).
| Block | Ruleset | When | Main targets |
|---|---|---|---|
| header | ruleset_header | once per file | .RECIPEPREFIX=+ |
| group | ruleset_group | once per file, from the first section | $(GARDEN_DL_DIR)/GROUP |
| common | ruleset_common | every system | GARDEN_SYSTEMS, all::, NAME.meta-data, NAME.user-data, clean:: |
| fetch | ruleset_fetch_common | every system | fetch, distclean::, .PRECIOUS, $(GARDEN_DL_DIR)/GROUP/NAME.qcow2 |
| URL | ruleset_fetch_direct or ruleset_fetch_prog | URL or URLProgram | $(GARDEN_DL_DIR)/GROUP/NAME.url |
| file name | ruleset_filename_static, _dynamic_basename or _dynamic_pattern | by the keys | $(GARDEN_DL_DIR)/GROUP/NAME.filename |
| boot | ruleset_x86_64_efi, _x86_64_bios, _aarch64_efi, _riscv64_efi, _loongarch64_efi, ruleset_s390x, ruleset_ppc64 | by Arch and Boot | NAME.run, NAME.qcow2 |
| footer | ruleset_footer | once per file | .RECIPEPREFIX= |
Sources: rulegen.py:447-738, rulegen.py:777-822. Which boot ruleset each combination gets is tabled in boot types.
| Lines | |
|---|---|
rules for ubuntu-cloud-24.04.x86_64 | 93 |
data/050-ubuntu.gen.mk (56 systems) | 5,224 |
all thirteen data/050-*.gen.mk (139 systems) | 13,135 |
data/000-systems.mk | 847 |
image-garden.mk | 15,889 |
| Problem | Output |
|---|---|
a mistake in the data: a missing or wrong key, an unknown Arch or Boot, a Boot the architecture lacks, two sections with one static cache file name, an INI syntax error, a missing file | data/X.ini: error: MESSAGE, exit status 1, no traceback |
a lone % in a value | a Python traceback ending in configparser.InterpolationSyntaxError |
When the Makefile runs it, make then deletes the empty data/050-X.gen.mk (.DELETE_ON_ERROR, Makefile:16-18) and the next make runs rulegen.py again.
The messages for each key are listed in the .ini files in data/ and URLProgram and local file names.
| Macro or command | Defined in | Called from |
|---|---|---|
CLOUD_INIT_META_DATA_TEMPLATE | mk/010-qemu.mk | NAME.meta-data |
PICK_CLOUD_INIT_USER_DATA_TEMPLATE_FOR | mk/010-qemu.mk | NAME.user-data |
GARDEN_LOG_SECTION, GARDEN_LOG_SUBSECTION, GARDEN_SYMLINK | mk/000-garden.mk | most recipes |
image-garden download-with-… | the image-garden script | the download rule |
EMIT_QEMU_RUN_SCRIPT_QUERY_PREAMBLE | mk/010-qemu.mk | NAME.run |
EMIT_QEMU_SYSTEM_ARCH_…_RUN_COMMAND, QEMU_SYSTEM_ARCH_…_CMDLINE | mk/010-qemu-ARCH.mk | NAME.run, NAME.qcow2 |
QEMU_IMG, QEMU_IMG_SIZE | mk/010-qemu.mk | NAME.qcow2 |
A section names its image with URL, a fixed address, or with URLProgram, a shell pipeline that prints the current one. Amazon Linux and Gentoo use URLProgram on x86_64 and aarch64.
[ubuntu-cloud-24.04.x86_64] writes its image address down with URL=https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img (ubuntu.ini:237-242).URLProgram are amazonlinux-cloud-2 and amazonlinux-cloud-2023 on x86_64 and aarch64 (amazonlinux.ini:8-42) and gentoo-cloud on both (gentoo.ini:8-22). Gentoo has no Release, so its names have none.url_program, "program for distributions without a stable URL" (rulegen.py:117-119), and requires exactly one of URL and URLProgram (rulegen.py:352-363).The pipeline becomes the recipe of $(GARDEN_DL_DIR)/gentoo/gentoo-cloud.x86_64.url. It is make syntax: $(CURL) is image-garden's curl, $$ is a dollar for the shell. The download, the @URL@ checksum address and the local file name all read the file it writes.
URLProgram, rulegen.py writes the .url rule with the program as its recipe, +{img.url_program} >$@, unchanged (rulegen.py:526-530, chosen at rulegen.py:793-795). A section with URL gets +echo {img.url} >$@ instead (rulegen.py:520-524).$(CURL) https://distfiles.gentoo.org/releases/amd64/autobuilds/latest-di-amd64-cloudinit.txt | awk 'NR==6 { print "https://distfiles.gentoo.org/releases/amd64/autobuilds/"$$1 }' (gentoo.ini:9). Amazon Linux's programs fetch the distribution's SHA256SUMS and let awk pick the one qcow2 entry that matches (amazonlinux.ini:9).CURL is curl --fail --silent --show-error --location, found on the PATH (000-garden.mk:21-21). make turns $$ into $ before the shell sees the line, so awk gets $1..url content on the slide come from a run on 21 November 2026 in a scratch build of the tag; the sixth line of Gentoo's file is the build's path and size..url file is read by the download recipe as its first prerequisite (rulegen.py:499-514), by @URL@, which expands to $$(cat $(word 1,$^)) (rulegen.py:82-88), and by the .filename rule (rulegen.py:546-553). Gentoo's checksum key is SHA256SUMS=@URL@.sha256 (gentoo.ini:12); Amazon Linux's is a fixed address.@URL@ and its rules..url, .filename, download and link of every system.The .filename rule names the cached image: the URL's last part by default, or LocalFilenameTemplate with @1 replaced by the one group of URLPattern. Gentoo's build is saved as gentoo-cloud-20261115T170104Z.x86_64.qcow2.
$(GARDEN_DL_DIR)/GROUP/NAME.filename (rulegen.py:134-136). With URL, it echoes LocalFilename or the URL's basename; with URLProgram, it reads the .url file and takes the basename, or, when the section has URLPattern and LocalFilenameTemplate, runs awk on it (rulegen.py:532-591, chosen at rulegen.py:782-799).URLPattern, cuts off the text before and after the capture group (rulegen.py works out both parts when it writes the rule), puts what is left in place of @1, and refuses an empty result, ., .. or one with a / (rulegen.py:546-591, rulegen.py:216-273).URLPattern=https://distfiles.gentoo.org/releases/amd64/autobuilds/([0-9]{8}T[0-9]{6}Z)/di-amd64-cloudinit-[0-9]{8}T[0-9]{6}Z\.qcow2$, LocalFilenameTemplate=gentoo-cloud-@1.x86_64.qcow2 (gentoo.ini:10-11). Amazon Linux 2023's group catches the version and leaves out the kernel (amazonlinux.ini:28-29)..url and .filename rules of a scratch build of the tag on 21 November 2026; ubuntu-cloud-24.04.x86_64.filename held noble-server-cloudimg-amd64.img.@1, a character neither make nor the shell treats specially; a template with $1 is rejected because it has no @1. rulegen.py also doubles every $ in the quoted pattern and template, so an anchor such as the pattern's final $ reaches awk intact (rulegen.py:138-158).The .url file depends on the makefiles only, so the build found first is kept until image-garden.mk or .image-garden.mk changes. A newer build then gets its own file name and download, the system's link moves to it, and the old build stays in dl/gentoo/.
.url rule's only prerequisite is $(MAKEFILE_LIST) (rulegen.py:526-530). When the generated rules are read, that list holds image-garden.mk and, if it exists, the project's .image-garden.mk, included by 999-local.mk:4-5. Nothing else makes make ask the distribution again..filename rule depends on the .url file (rulegen.py:546-548), and the cached link dl/gentoo/gentoo-cloud.x86_64.qcow2 on both; its recipe downloads to the new local name and replaces the link in one rename with GARDEN_SYMLINK (rulegen.py:510-514, 000-garden.mk:58-64).gentoo-cloud.x86_64.qcow2 is an overlay made with qemu-img create -b on that link (rulegen.py:601-604). That make prepares it again once the link points at a newer download is derived from the rule, not tried.distclean removes the file the link points at, the file .filename names, the link, .url and .filename (rulegen.py:486-492); earlier builds have no link and are left alone (derived). <next> on the slide stands for the newer build's stamp..url file is made again with the same address, the download rule runs again and verifies the cached image without fetching it; the documentation does not mention it.At build time: both or neither of URL and URLProgram, LocalFilename with a program, half a pattern and template pair, a pattern without exactly one group, a template without @1. At make time: a URL that does not match. Not checked for programs: the architecture in the URL and clashing names.
data/FILE.ini: error: MESSAGE, one line with no traceback, and rulegen.py exits with status 1 (rulegen.py:753-757); make then deletes the empty data/050-FILE.gen.mk. The messages on the slide were produced by running rulegen.py at the pinned commit on small INI files in a scratch directory.URL and URLProgram; URLPattern, LocalFilenameTemplate only with URLProgram, and only as a pair; LocalFilename only with URL (rulegen.py:358-394).(?:…) groups do not count); the template must contain @1, no @2 or higher, no /, and not be . or .. (rulegen.py:183-213). A template written with $1 fails the @1 check.amd64 and arm64 count for x86_64 and aarch64) only when the section has URL (rulegen.py:406-416).LocalFilename, the URL's basename, or a template without @1 (rulegen.py:160-169, rulegen.py:758-775); a clash is reported as data/FILE.ini: error: per-group local filename collision in group 'G': 'F' used by 'S1' and 'S2'. tests/check-rulegen.sh covers the local file name keys and the clash (tests/check-rulegen.sh:111-170). A template with @1 is skipped, so the architecture in Gentoo's and Amazon Linux's templates is what keeps their names apart..url recipe ends in awk (rulegen.py:526-530) and the filename recipe in | tee $@ (rulegen.py:546-591), so a failing program or a URL that no longer matches writes empty files, make exits 0, and later runs fail with "curl: (3) URL rejected: No host part in the URL" until a makefile changes or the files are deleted. Run at the commit in garden.commit with CURL=false.Next: the checksum placeholder, the target chain, downloads, the first-boot quirks of Amazon Linux 2 and Gentoo, the rest of rulegen.py's rules, and the cache.
URLProgram= a make recipe that prints the image URL; URLPattern= a regular expression with one capture group; LocalFilenameTemplate= a file name with @1.Read in rulegen.py, data/amazonlinux.ini, data/gentoo.ini, data/README.md, NEWS, mk/000-garden.mk and the image-garden script of image-garden at the pinned commit ("code"). The resolved URLs and file names were produced on 21 November 2026 by running the .url and .filename rules of a scratch build of the tag, and the error messages by running the pinned rulegen.py on small INI files ("run"); the build stamps change whenever the distributions publish. What happens to the cache and the prepared disk when a newer build appears is reasoned from the rules ("derived").
| Key | Goes with | Value | Checked by rulegen.py |
|---|---|---|---|
URL | a fixed address | the image URL | must contain the architecture (amd64, arm64 count) |
URLProgram | no URL | a make recipe that prints the image URL | exactly one of URL and URLProgram |
LocalFilename | URL only | the cached file name | no /, not . or .., no clash in the file |
URLPattern | URLProgram only, with the template | a regular expression with exactly one capture group | compiles; one capturing group; balanced brackets |
LocalFilenameTemplate | URLProgram only, with the pattern | a file name with @1 | contains @1, no @2 or higher, no / |
Sources: rulegen.py:183-214, rulegen.py:352-416, data/README.md:71-88.
| System | The program reads | Capture group | Cached as (21 November 2026) |
|---|---|---|---|
amazonlinux-cloud-2.x86_64 | os-images/latest/kvm/SHA256SUMS | version | amazonlinux-cloud-2-VERSION.x86_64.qcow2 |
amazonlinux-cloud-2.aarch64 | os-images/latest/kvm-arm64/SHA256SUMS | version | amazonlinux-cloud-2-VERSION.aarch64.qcow2 |
amazonlinux-cloud-2023.x86_64 | al2023/os-images/latest/kvm/SHA256SUMS | version | amazonlinux-cloud-2023-2023.12.20261120.0.x86_64.qcow2 |
amazonlinux-cloud-2023.aarch64 | al2023/os-images/latest/kvm-arm64/SHA256SUMS | version | amazonlinux-cloud-2023-VERSION.aarch64.qcow2 |
gentoo-cloud.x86_64 | latest-di-amd64-cloudinit.txt, line 6 | build stamp | gentoo-cloud-20261115T170104Z.x86_64.qcow2 |
gentoo-cloud.aarch64 | latest-di-arm64-cloudinit.txt, line 6 | build stamp | gentoo-cloud-STAMP.aarch64.qcow2 |
Amazon Linux checks its images against the same SHA256SUMS file its program reads; Gentoo uses SHA256SUMS=@URL@.sha256, the checksum file next to the image (amazonlinux.ini:8-42, gentoo.ini:8-22). Only the rows with a full name were run.
$(CURL) is curl --fail --silent --show-error --location (000-garden.mk:21-21); write $$ for every $ the shell or awk should see.$(GARDEN_DL_DIR)/GROUP/NAME.url (rulegen.py:526-530).image-garden.mk or .image-garden.mk, not on every make.% must be written %%: rulegen.py reads the files with Python's default interpolation, and a lone % stops it with an InterpolationSyntaxError traceback, the one data mistake still reported that way (run at the pinned commit; no file in data/ has one).In $(GARDEN_DL_DIR)/gentoo/, by default ~/.cache/image-garden/dl/gentoo/:
| File | Made from | Content |
|---|---|---|
gentoo-cloud.x86_64.url | the program | the image URL |
gentoo-cloud.x86_64.filename | the .url file, the pattern and the template | gentoo-cloud-STAMP.x86_64.qcow2 |
gentoo-cloud-STAMP.x86_64.qcow2 | image-garden download-with-sha256sums | the verified image |
gentoo-cloud.x86_64.qcow2 | GARDEN_SYMLINK | a link to the image |
| When | Message |
|---|---|
| build | Image 'NAME' defines both URL and URLProgram |
| build | Image 'NAME' defines neither URL nor URLProgram |
| build | Image 'NAME' defines URLPattern but uses URL |
| build | Image 'NAME' defines LocalFilenameTemplate but uses URL |
| build | Image 'NAME' defines LocalFilename but uses URLProgram; use URLPattern and LocalFilenameTemplate |
| build | Image 'NAME' must define both URLPattern and LocalFilenameTemplate together |
| build | Image 'NAME' has invalid URLPattern: … |
| build | Image 'NAME' URLPattern must contain exactly one capture group |
| build | Image 'NAME' LocalFilenameTemplate must contain '@1' placeholder |
| build | Image 'NAME' LocalFilenameTemplate supports only '@1' placeholder |
| make | URL for NAME does not match URLPattern |
| make | Unresolved capture group in LocalFilenameTemplate for NAME |
| make | Invalid resolved local filename for NAME: … |
Build-time messages are printed as data/FILE.ini: error: MESSAGE, without a traceback (rulegen.py:753-757).
A .image-garden.mk in your project changes the cloud-init user-data of the images image-garden makes for it.
mk/999-local.mk includes it: -include $(GARDEN_PROJECT_DIR)/.image-garden.mk (999-local.mk:4-5).root and the distribution user, SSH password logins, power off at the end (010-qemu.mk:187-247).image-garden runs make with your project directory; the last of image-garden's own make files includes .image-garden.mk, after image-garden's settings and before the generated system rules.
GARDEN_PROJECT_DIR is the directory image-garden runs in (image-garden:7); image-garden make passes it to make with -f image-garden.mk (image-garden:982-993).mk/999-local.mk is -include $(GARDEN_PROJECT_DIR)/.image-garden.mk; the leading - makes a missing file no error (999-local.mk:4-5).image-garden.mk is data/000-systems.mk, then the sorted mk/*.mk (so 999-local.mk last), then the generated data/050-*.gen.mk (Makefile:48-50). A variable defined in your file therefore replaces one defined in mk/, and is defined before the system rules expand it.EXTRA_CLOUD_INIT_FILES adds to write_files; EXTRA_CLOUD_INIT_APT_CONFIG adds a top-level section such as apt:. Both get the group as $1 and the release as $2.
mk/010-qemu.mk declares both hooks (010-qemu.mk:47-48). The common template calls $(call EXTRA_CLOUD_INIT_APT_CONFIG,$1,$(value 3)) at the top level, right after ssh_pwauth (010-qemu.mk:197-198), and $(call EXTRA_CLOUD_INIT_FILES,$1,$(value 3)) at the end of write_files (010-qemu.mk:236-237). In the template $1 is the group and $(value 3) the release, so inside a hook they arrive as $1 and $2.EXTRA_CLOUD_INIT_FILES starts empty. EXTRA_CLOUD_INIT_APT_CONFIG is already used by image-garden for old Ubuntu releases: see the next slide./etc/my-test.conf and its content are an illustrative example, not taken from image-garden and not run for this map.write_files and apt.image-garden defines EXTRA_CLOUD_INIT_APT_CONFIG for end-of-life Ubuntu releases. Its own .image-garden.mk redefines it and calls UBUNTU_OLD_RELEASES_APT_CONFIG inside, keeping both.
mk/050-ubuntu.mk lists the end-of-life releases that need old-releases.ubuntu.com (050-ubuntu.mk:12), defines UBUNTU_OLD_RELEASES_APT_CONFIG (050-ubuntu.mk:15-24) and sets EXTRA_CLOUD_INIT_APT_CONFIG to call it (050-ubuntu.mk:26-28)..image-garden.mk redefines the hook: APT::Install-Recommends "false" and the old-releases configuration with its leading apt: removed by $(subst apt:,,…), so there is one apt: map (.image-garden.mk:5-14). Its comment: QEMU with its recommends meant 319 packages on Ubuntu 26.04 instead of 81.Slow, stable setup goes in cloud-init: it runs once, when make builds the image. What depends on the code under test stays in prepare:, which runs on every fresh -snapshot machine.
allocate starts the .run script with -snapshot unless QEMU_SNAPSHOT_OPTION says otherwise, so each machine starts from the prepared image and its changes are thrown away (image-garden:1153-1163).X.qcow2 (rulegen.py:593-610); it runs again only when the image is rebuilt..image-garden.mk installs python3, make, whois, xorriso, curl, qemu-utils and QEMU for a nested VM through cloud-init (.image-garden.mk:43-58), while its spread.yaml top-level prepare: builds and installs image-garden itself (spread.yaml:73-77).prepare: on each machine it allocates, a suite's prepare: before that suite, and prepare-each: before every task. With fresh machines per run, all of them are paid on every run..image-garden.mk rebuilds the images (next slide). For the cost over many runs drawn as two timelines, see paid for once.Each .user-data depends on .image-garden.mk. An edit remakes the user-data, the seed and the prepared disk of every system in the project; downloads are kept.
X.user-data: $(MAKEFILE_LIST) $(wildcard $(GARDEN_PROJECT_DIR)/.image-garden.mk) (rulegen.py:467-471); named instances have the same dependency (020-instances.mk:75-76). Because the file is included, it is also in $(MAKEFILE_LIST), which the meta-data and .run rules depend on.X.qcow2 depends on the download, X.seed.iso and the firmware copies, and its recipe creates the overlay and runs the provisioning boot (rulegen.py:593-610); the seed is made from the user-data and meta-data (010-qemu.mk:268-279)..image-garden.mk, so an edit downloads nothing.Next: how a template is chosen, named instances, and several systems from one base image.
make waits for QEMU to exit. The guest ends the provisioning boot by powering off, and switches cloud-init off for every later boot.
tee X.qcow2.log; the recipe ends when QEMU exits (rulegen.py:601-609). The .run rule is ordered after the image, through | X.qcow2 when GARDEN_RUN_REQUIRES_QCOW2 is set, which it is by default (rulegen.py:594, 010-qemu.mk:14).power_state block (010-qemu.mk:190-195) and touch /etc/cloud/cloud-init.disabled (010-qemu.mk:246).-no-shutdown.power_state: {delay: now, mode: poweroff, message: Powering off, timeout: 0, condition: true}. The console goes to ubuntu-cloud-24.04.x86_64.qcow2.log.
power_state: with delay: now, mode: poweroff, message: Powering off, timeout: 0, condition: true (010-qemu.mk:190-195). The Ubuntu Core template has the same block (050-ubuntu-core.mk:135-140).set -o pipefail && <QEMU command> … 2>&1 | tee X.qcow2.log (rulegen.py:606-609); the display defaults to -nographic, so the serial console reaches the log (010-qemu.mk:13).runcmd script, and condition: true means it acts whatever happened before.power_state, and its template powers off by hand: see what differs per distribution.The last runcmd command is touch /etc/cloud/cloud-init.disabled. It stops cloud-init on every later boot, not on this one.
touch /etc/cloud/cloud-init.disabled is the last command of the common template's runcmd list, after pkgproxy's late setup (010-qemu.mk:238-247)./etc/cloud/cloud-init.disabled and, when it exists, keeps cloud-init's services from running. A file created while cloud-init runs does not stop that run.$(CLOUD_INIT_USER_DATA_TEMPLATE) run after this one, in the same boot; see how a user-data template is chosen..run keeps changes in the overlay; allocate adds -snapshot and keeps none. Neither provisions again; a new user-data makes make prepare the image again.
.run script attaches only the overlay, as the boot disk (010-qemu-x86_64.mk:59-108); writes go to X.qcow2, the base image stays as downloaded.allocate runs the script with -snapshot unless QEMU_SNAPSHOT_OPTION says otherwise, in the background with a pid file (image-garden:1153-1163). Derived, from QEMU's behaviour: with -snapshot writes go to a temporary file and are lost when QEMU exits..image-garden.mk (rulegen.py:467-471); the image depends on the seed made from it (rulegen.py:601-604), so a new user-data means a new overlay and a new provisioning boot.bootcmd, then write_files and packages, then runcmd in order, with template lines after the touch, then power_state.
PKGPROXY_BOOTCMD_SETUP "runs from bootcmd, early in the first boot, so that cloud-init's own package installs (packages: in a custom template) already go through pkgproxy", and PKGPROXY_RUNCMD_SETUP "runs from runcmd, at the end of the first boot", because the snap script restarts snapd (010-qemu.mk:108-126). The two blocks are at 010-qemu.mk:156-168.runcmd list: hosts, SSH snippet, PermitRootLogin sed, apt sed, pkgproxy's late setup, then touch /etc/cloud/cloud-init.disabled (010-qemu.mk:238-246).$(CLOUD_INIT_USER_DATA_TEMPLATE) and adds dash lines extends that list after the touch; Amazon Linux 2's shutdown --poweroff now is such a line (050-amazonlinux-2.mk:4-8).bootcmd runs in an early stage on every boot cloud-init runs; write_files runs before the package module; the package module runs before the runcmd script; the power-state module runs last.No timeout: a guest that never powers off keeps make waiting. A failed command still powers off and counts as success. An interrupted or failed boot deletes X.qcow2.
set -o pipefail && <QEMU command> … 2>&1 | tee X.qcow2.log (rulegen.py:606-609). With pipefail, a QEMU that exits non-zero fails the recipe even though tee succeeds..DELETE_ON_ERROR: removes a target whose recipe failed (000-garden.mk:4-7); The pattern .PRECIOUS: %.qcow2 %.img (010-qemu.mk:334) is meant for the converted downloads; it does not protect the overlay, whose rule is explicit. Run for this map with GNU make 4.4.1 on a two-line makefile of the same shape: a failing explicit x.qcow2 rule had its target deleted. On an interrupt GNU make deletes a target that is not precious (derived).condition: true in power_state (010-qemu.mk:190-195). Derived, from cloud-init's behaviour: a failing runcmd command does not stop the rest of the list or the power-off, so QEMU exits with status 0.power_state: see start from the common template. Amazon Linux 2 ignores power_state and has its own shutdown: see what differs per distribution.set -o pipefail (050-ubuntu-core.mk:37-53, 050-ubuntu-core.mk:77-106), so a QEMU that fails there fails the build too.Next: the seed, templates and hooks, allocate, the per-distribution quirks, and the serial console.
Read in rulegen.py, mk/000-garden.mk, mk/010-qemu.mk and image-garden of image-garden at the commit this map describes ("code"). When cloud-init runs each part is cloud-init's behaviour ("derived"). One run: a GNU make 4.4.1 test that a failing explicit %.qcow2 target is deleted under .DELETE_ON_ERROR despite the pattern .PRECIOUS.
| Step | From | Notes |
|---|---|---|
bootcmd | pkgproxy's part (010-qemu.mk:156-162) | only when a pkgproxy is reachable from guests |
write_files, users, packages | the template | packages: only in a project template |
runcmd, the common part | 010-qemu.mk:238-246 | ends with touch /etc/cloud/cloud-init.disabled |
runcmd, a template's lines | the project or a quirk | after the touch; Amazon Linux 2's shutdown --poweroff now |
power_state | 010-qemu.mk:190-195 | poweroff, delay: now, condition: true |
| Seed | cloud-init | Changes kept | |
|---|---|---|---|
provisioning boot (make X.qcow2) | attached | runs once | in X.qcow2 |
./X.run | not attached | off | in X.qcow2 |
image-garden allocate | not attached | off | no: -snapshot |
| What happens | What make does | What to do |
|---|---|---|
| the guest never powers off | waits; there is no timeout | read X.qcow2.log; check that the template starts from the common one |
a runcmd command fails | finishes; the image counts as made (derived) | read X.qcow2.log; rm X.qcow2 and make again |
| QEMU exits non-zero | fails the recipe (set -o pipefail) and deletes X.qcow2 (000-garden.mk:4-7) | fix the cause and make again |
| make is interrupted | deletes X.qcow2 (derived) | make again |
A project's .image-garden.mk can define extra systems from one base image, each with its own cloud-init profile, so their setup is done once instead of in every test run.
image-garden make includes the project's .image-garden.mk through -include $(GARDEN_PROJECT_DIR)/.image-garden.mk (999-local.mk:5). The README lists what it is for: project dependencies, cloud-init per distribution, release or named instance, named instances, and extra first-boot commands (README.md:949-965).$(eval $(call define-instance,opensuse-cloud-16.0,apparmor)) makes opensuse-cloud-16.0@apparmor.x86_64: its own user-data, seed, overlay and .run, on the base system's download.
define-instance takes a base system, with or without the architecture, and an instance name; without an architecture it uses GARDEN_ARCH (020-instances.mk:4-28). The result for this example is opensuse-cloud-16.0@apparmor.x86_64.$(GARDEN_DL_DIR)/<group>/<base>.qcow2, with qemu-img create -f qcow2 -b (020-instances.mk:96-98).data/000-systems.mk (020-instances.mk:47-51). The base used here is [opensuse-cloud-16.0.x86_64] (opensuse.ini:50-55).data/*.ini, which is every system but Ubuntu Core: its systems are made by rules of their own and have no instances. define-instance with an Ubuntu Core system lists the instance in list-systems, but make has no rule for it (020-instances.mk:9-10, README.md:976-979).base-release-instance, for example ubuntu-24-04-webserver (README.md:988-989).The most specific template wins: OPENSUSE_16.0@apparmor_CLOUD_INIT_USER_DATA_TEMPLATE first, CLOUD_INIT_USER_DATA_TEMPLATE last. A template starts with $(CLOUD_INIT_USER_DATA_TEMPLATE) and appends to its runcmd:.
GROUP_RELEASE@INSTANCE_, GROUP@INSTANCE_, GROUP_RELEASE_, GROUP_, each followed by CLOUD_INIT_USER_DATA_TEMPLATE, then CLOUD_INIT_USER_DATA_TEMPLATE itself (010-qemu.mk:293-298). For an instance the group is passed in capitals and the instance name as given (020-instances.mk:75), so the first name for this example is OPENSUSE_16.0@apparmor_CLOUD_INIT_USER_DATA_TEMPLATE. The README documents the same order (README.md:1046-1051).CLOUD_INIT_USER_DATA_TEMPLATE is the common template, BASE_CLOUD_INIT_USER_DATA_TEMPLATE (010-qemu.mk:249). It sets the users, SSH and power_state, and ends with runcmd: (010-qemu.mk:187-247).runcmd, so commands can be appended as a YAML list (README.md:1061-1070).touch /etc/cloud/cloud-init.disabled (010-qemu.mk:246). That file stops cloud-init on later boots, not the current one.Boot settings changed during provisioning apply from the next boot, the first one your tests see. The base system keeps the distribution's defaults.
power_state, 010-qemu.mk:190-196), so a kernel command line written during provisioning is first used by the next boot, the first boot of the prepared image.GRUB_TIMEOUT=0 and regenerates the grub configuration (.image-garden.mk:6-14).A packages: list in a template installs software during the provisioning boot. image-garden's own .image-garden.mk installs QEMU and firmware for nested VMs, without recommends.
.image-garden.mk turns off recommended packages in an EXTRA_CLOUD_INIT_APT_CONFIG; its comment counts 319 packages with recommends and 81 without, for QEMU on Ubuntu 26.04 (.image-garden.mk:5-14).qemu-system-* for the guest's architecture and its UEFI firmware, for nested VMs (.image-garden.mk:33-55); Debian uses the same template (.image-garden.mk:58).ubuntu-cloud-24.04@mc and installs mc in it (.image-garden.mk:16-23).The provisioning boot pays the install cost once, at make time. Each allocate starts from the prepared overlay with -snapshot, so runs neither repeat the install nor change the image.
.qcow2 rule creates the overlay and runs the provisioning boot once; make does not run it again while the overlay is newer than its inputs (020-instances.mk:96-103).allocate runs the .run script with -snapshot unless QEMU_SNAPSHOT_OPTION says otherwise, so writes go to a temporary file and the prepared overlay is not changed (image-garden:1153-1163).Editing .image-garden.mk makes every system's user-data, seed and overlay out of date. The download is kept; the provisioning boot runs again.
$(MAKEFILE_LIST) and $(wildcard $(GARDEN_PROJECT_DIR)/.image-garden.mk) (020-instances.mk:75-76); the generated rules give every other system the same dependency (rulegen.py:467-468)..image-garden.mk reaches the overlay and its provisioning boot.git-restore-mtime for this reason; see how the action caches.In spread.yaml the instance is opensuse-cloud-16.0-at-apparmor; allocate maps -at- to @ and adds the architecture. The credentials are the base system's, opensuse/opensuse, and --query lists them.
+ to be written -plus- and @ to be written -at- in spread system names, and shows the allocate lines that map them back (README.md:720-732). image-garden's own spread.yaml does the same and adds the architecture (spread.yaml:45-47).root/root and the group's user. Its launcher's --query lists them, as a base system's does: the rule passes root distro and the group (020-instances.mk:89) to the preamble that prints system.users.0 and system.users.1 (010-qemu.mk:80-88). spread itself still reads them from spread.yaml.Next: named instances, the template lookup order, the simpler hooks, spread names, allocate and the provisioning boot.
define-instance for the system, a template named after it that starts with $(CLOUD_INIT_USER_DATA_TEMPLATE), and make pays the provisioning once.The mechanics, define-instance, the template lookup and the rebuild rules, were read in the image-garden source at the commit this map describes ("code"). The template names for the examples follow from the lookup rule ("derived"). The openSUSE AppArmor commands are illustrative: they are not part of image-garden and were not run for this map.
Put it next to your tests, where you run image-garden make or spread.
# Two systems from one openSUSE download: the base system, # opensuse-cloud-16.0.x86_64, boots with SELinux as it ships; # this instance boots with AppArmor. $(eval $(call define-instance,opensuse-cloud-16.0,apparmor)) # Illustrative: check the pattern and the bootloader tool for your release. define OPENSUSE_16.0@apparmor_CLOUD_INIT_USER_DATA_TEMPLATE $(CLOUD_INIT_USER_DATA_TEMPLATE) - zypper --non-interactive install -t pattern apparmor - sed -i 's/security=selinux selinux=1/security=apparmor/' /etc/default/grub - update-bootloader --refresh endef # Heavy software, installed once into every Ubuntu image of the project. define UBUNTU_CLOUD_INIT_USER_DATA_TEMPLATE $(CLOUD_INIT_USER_DATA_TEMPLATE) packages: - build-essential - postgresql - qemu-system-x86 endef
runcmd:, so lines starting with - right after it are more commands.packages: starts a new top-level key after the commands.| Order | Variable name | Used by |
|---|---|---|
| 1 | OPENSUSE_16.0@apparmor_CLOUD_INIT_USER_DATA_TEMPLATE | opensuse-cloud-16.0@apparmor only |
| 2 | OPENSUSE@apparmor_CLOUD_INIT_USER_DATA_TEMPLATE | every @apparmor instance of openSUSE |
| 3 | OPENSUSE_16.0_CLOUD_INIT_USER_DATA_TEMPLATE | openSUSE 16.0 without a more specific template |
| 4 | OPENSUSE_CLOUD_INIT_USER_DATA_TEMPLATE | every openSUSE system without a more specific template |
| 5 | CLOUD_INIT_USER_DATA_TEMPLATE | the common template, for everything else |
The same order with UBUNTU, UBUNTU_24.04 and an instance such as @mc applies to Ubuntu: image-garden's spread demo defines UBUNTU_24.04@mc_CLOUD_INIT_USER_DATA_TEMPLATE.
| Garden name | spread name | User and password |
|---|---|---|
opensuse-cloud-16.0.x86_64 | opensuse-cloud-16.0 | opensuse / opensuse |
opensuse-cloud-16.0@apparmor.x86_64 | opensuse-cloud-16.0-at-apparmor | opensuse / opensuse |
The allocate script maps -at- back to @ and adds .$(uname -m). See names in spread. Each instance's .run script lists the same users under --query.
Every system defined in data/*.ini. Ubuntu Core's systems are made by rules of their own and have no instances: define-instance with one lists the instance in list-systems, but make has no rule for it (README.md:976-979).
mk/050-amazonlinux-2.mk, mk/050.gentoo.mk and mk/050-ubuntu.mk adjust the common user-data. Ubuntu Core has its own template.
mk/050-amazonlinux-2.mk defines AMAZONLINUX_2_CLOUD_INIT_USER_DATA_TEMPLATE (050-amazonlinux-2.mk:4-8); mk/050.gentoo.mk defines GENTOO_CLOUD_INIT_USER_DATA_TEMPLATE (050.gentoo.mk:4-8); mk/050-ubuntu.mk defines EXTRA_CLOUD_INIT_APT_CONFIG (050-ubuntu.mk:4-28).BASE_UBUNTU_CORE_CLOUD_INIT_USER_DATA_TEMPLATE (050-ubuntu-core.mk:131-179); see Ubuntu Core images.image-garden.mk is built from data/000-systems.mk, then every mk/*.mk in sorted order, then the generated rules (Makefile:48-49).mk/ defines a template or a hook for a distribution: the remaining files are QEMU per architecture, the instance macro and the project hook.AMAZONLINUX_2_CLOUD_INIT_USER_DATA_TEMPLATE is the common template plus - shutdown --poweroff now. Amazon Linux 2023 uses the common one.
$(BASE_CLOUD_INIT_USER_DATA_TEMPLATE) followed by - shutdown --poweroff now (050-amazonlinux-2.mk:4-8).AMAZONLINUX_2_CLOUD_INIT_USER_DATA_TEMPLATE (group and release) before AMAZONLINUX_… and the common one (010-qemu.mk:293-298); for release 2023 no such name is defined, so the common template is used.runcmd list with touch /etc/cloud/cloud-init.disabled (010-qemu.mk:246), so the added line comes after it.QEMU_CPU_AARCH64=neoverse-n1 is set for the .qcow2 and .run of amazonlinux-cloud-2.aarch64 and amazonlinux-cloud-2023.aarch64 (050-amazonlinux-2.mk:10-11); the README notes it too (README.md:621-625).GENTOO_CLOUD_INIT_USER_DATA_TEMPLATE is the common template plus - systemctl enable --now sshd.service, in mk/050.gentoo.mk.
$(BASE_CLOUD_INIT_USER_DATA_TEMPLATE) followed by - systemctl enable --now sshd.service (050.gentoo.mk:4-8).data/gentoo.ini have no Release= (gentoo.ini:8-22), so the systems are gentoo-cloud.x86_64 and gentoo-cloud.aarch64, and their host name is gentoo.image-garden.mk includes $(sort $(filter mk/%.mk,$^)) from $(wildcard mk/*.mk) (Makefile:48-49), so mk/050.gentoo.mk is included like the others, after mk/050-ubuntu.mk in sort order. Nothing in it depends on that order (derived): the template is a recursive variable, expanded only when a rule uses it.UBUNTU_OLD_RELEASES_VERSIONS lists 16.10 to 24.10. For those, EXTRA_CLOUD_INIT_APT_CONFIG adds apt: with preserve_sources_list: false and old-releases for primary and security.
UBUNTU_OLD_RELEASES_VERSIONS = 16.10 17.04 17.10 18.10 19.04 19.10 20.10 21.04 21.10 22.10 23.04 23.10 24.10, with the rule "if the release codename does not appear in https://archive.ubuntu.com/ubuntu/dists/ then apt must use old-releases" and the note that 25.04 and 25.10 were end of life but still in archive.ubuntu.com when the list was checked (050-ubuntu.mk:4-12).UBUNTU_OLD_RELEASES_APT_CONFIG emits the apt: block only when the group is ubuntu and the release is on the list: preserve_sources_list: false, and primary and security with arches: [default] and uri: http://old-releases.ubuntu.com/ubuntu (050-ubuntu.mk:14-24). EXTRA_CLOUD_INIT_APT_CONFIG calls it with the group and release (050-ubuntu.mk:26-28), and the common template calls the hook (010-qemu.mk:198).data/ubuntu.ini; see Ubuntu cloud images.preserve_sources_list: false makes cloud-init write the sources itself from primary and security.A project's GENTOO_… template replaces image-garden's; an AMAZONLINUX_… group template loses to AMAZONLINUX_2_…. Keep the systemctl and shutdown lines.
mk/999-local.mk includes $(GARDEN_PROJECT_DIR)/.image-garden.mk (999-local.mk:4-5), after every other mk/*.mk, so a define there of an existing name replaces it.amazonlinux-cloud-2 the group-release name AMAZONLINUX_2_CLOUD_INIT_USER_DATA_TEMPLATE is always defined by image-garden (050-amazonlinux-2.mk:5-8), so a project's AMAZONLINUX_CLOUD_INIT_USER_DATA_TEMPLATE applies only to Amazon Linux 2023.$(BASE_CLOUD_INIT_USER_DATA_TEMPLATE), not from $(CLOUD_INIT_USER_DATA_TEMPLATE) (050-amazonlinux-2.mk:6, 050.gentoo.mk:6). Derived: a project that redefines CLOUD_INIT_USER_DATA_TEMPLATE to change every system does not change Amazon Linux 2 or Gentoo, which keep image-garden's base.Next: the template lookup, the hooks, provisioning, Ubuntu Core, and the Ubuntu releases.
Read in mk/050-amazonlinux-2.mk, mk/050.gentoo.mk, mk/050-ubuntu.mk, mk/010-qemu.mk, mk/999-local.mk and the Makefile of image-garden v0.8.0 ("code"). What a project template does to these is worked out from the picker ("derived").
| File | Defines | Applies to | Change |
|---|---|---|---|
mk/050-amazonlinux-2.mk | AMAZONLINUX_2_CLOUD_INIT_USER_DATA_TEMPLATE | amazonlinux-cloud-2.* | - shutdown --poweroff now after the common runcmd (050-amazonlinux-2.mk:4-8) |
mk/050-amazonlinux-2.mk | QEMU_CPU_AARCH64=neoverse-n1 | amazonlinux-cloud-2.aarch64, amazonlinux-cloud-2023.aarch64 | QEMU's CPU model, not cloud-init (050-amazonlinux-2.mk:10-11) |
mk/050.gentoo.mk | GENTOO_CLOUD_INIT_USER_DATA_TEMPLATE | gentoo-cloud.* | - systemctl enable --now sshd.service after the common runcmd (050.gentoo.mk:4-8) |
mk/050-ubuntu.mk | EXTRA_CLOUD_INIT_APT_CONFIG | Ubuntu 16.10, 17.04, 17.10, 18.10, 19.04, 19.10, 20.10, 21.04, 21.10, 22.10, 23.04, 23.10, 24.10 | an apt: block for http://old-releases.ubuntu.com/ubuntu (050-ubuntu.mk:4-28) |
mk/050-ubuntu-core.mk | UBUNTU_CORE_CLOUD_INIT_USER_DATA_TEMPLATE | ubuntu-core-* | a template of its own; see Ubuntu Core images |
You define in .image-garden.mk | Effect on Amazon Linux 2 | Effect on Gentoo |
|---|---|---|
CLOUD_INIT_USER_DATA_TEMPLATE | none: its template starts from BASE_… | none: its template starts from BASE_… |
AMAZONLINUX_CLOUD_INIT_USER_DATA_TEMPLATE | none: AMAZONLINUX_2_… is more specific; Amazon Linux 2023 uses yours | – |
AMAZONLINUX_2_CLOUD_INIT_USER_DATA_TEMPLATE | replaces image-garden's: keep - shutdown --poweroff now last | – |
GENTOO_CLOUD_INIT_USER_DATA_TEMPLATE | – | replaces image-garden's: keep - systemctl enable --now sshd.service |
EXTRA_CLOUD_INIT_APT_CONFIG | – | – (replaces the old-releases block for Ubuntu: see changing what cloud-init does) |
The project file is included last (999-local.mk:4-5); the picker takes the first defined name (010-qemu.mk:293-298).
A cloud image expects a cloud to configure it. cloud-init's NoCloud data source reads a disk labelled cidata instead, and image-garden makes one for every system.
xorriso -as genisoimage -volid cidata (010-qemu.mk:263-279).data/*.ini gets a meta-data and a user-data rule (rulegen.py:461-471); the image rule takes the seed as its second prerequisite and boots with it (rulegen.py:601-609).datasource_list: [NoCloud] in /etc/cloud/cloud.cfg.d/99-image-garden.cfg (010-qemu.mk:221-230).cidata holding files named user-data and meta-data.X.meta-data comes from the meta-data template with group and release; X.user-data from the picked template with group, user name and release. Both are echoed through tee, so they appear in the build log.
data/*.ini: X.meta-data: export META_DATA = $(call CLOUD_INIT_META_DATA_TEMPLATE,{img.group},{img.release}) and X.user-data: export USER_DATA = $(call $(call PICK_CLOUD_INIT_USER_DATA_TEMPLATE_FOR,{img.group.name_upper},{img.release}),{img.group},{img.group},{img.release}); each recipe runs echo "$${…}" | tee $@, then touch --reference= the newest prerequisite (rulegen.py:461-471).$(MAKEFILE_LIST); the user-data on $(MAKEFILE_LIST) and $(wildcard $(GARDEN_PROJECT_DIR)/.image-garden.mk) (rulegen.py:462, rulegen.py:468).PICK_CLOUD_INIT_USER_DATA_TEMPLATE_FOR (010-qemu.mk:293-298); see how a template is chosen.instance-id: iid-ubuntu-24-04 and local-hostname: ubuntu-24-04: group, release and instance, with dots and pluses turned into dashes. The user-data's hostname is the same name.
#cloud-config, instance-id: iid-$(call CLOUD_INIT_HOSTNAME,…) and local-hostname: $(call CLOUD_INIT_HOSTNAME,…), called with the group, the release and, for a named instance, the instance name (010-qemu.mk:99-106).CLOUD_INIT_HOSTNAME joins group, release and instance with dashes and turns dots and pluses into dashes, "not allowed in a host name label" (010-qemu.mk:94-97).data/*.ini passes {img.group},{img.release} (rulegen.py:461), a named instance its base system's group and release and its own name (020-instances.mk:68), and Ubuntu Core ubuntu-core and the release with its modifiers, such as 24+tpm (050-ubuntu-core.mk:111, :121).hostname: and the 127.0.0.1 line of /root/hosts.APPEND use the same function with the same values (010-qemu.mk:196, 010-qemu.mk:231-235); the first runcmd command appends that line to /etc/hosts (010-qemu.mk:238-240). The Ubuntu Core template's hostname: does the same (050-ubuntu-core.mk:141).GARDEN_ARCH=x86_64 in a scratch project that defines the webserver instance: image-garden make wrote iid-ubuntu-24-04/ubuntu-24-04, iid-ubuntu-24-04-webserver/ubuntu-24-04-webserver, iid-ubuntu-core-24-tpm/ubuntu-core-24-tpm and, for Gentoo, which has no release, iid-gentoo/gentoo; the user-data hostname: lines matched.instance-id and local-hostname from the meta-data, and a hostname: in the user-data sets the host name; here both say the same.The common template, top to bottom: time zone, power_state, hostname, ssh_pwauth, the apt and pkgproxy hooks, users, write_files and runcmd.
BASE_CLOUD_INIT_USER_DATA_TEMPLATE (010-qemu.mk:187-247), in order: timezone: Europe/Warsaw (189), power_state (190-195), hostname (196), ssh_pwauth: true (197), the EXTRA_CLOUD_INIT_APT_CONFIG hook (198), pkgproxy's bootcmd (199), users (200-211), write_files (212-237, ending with pkgproxy's injected files and the EXTRA_CLOUD_INIT_FILES hook), runcmd (238-246).bootcmd and runcmd parts are empty when no pkgproxy is reachable from the guest (010-qemu.mk:156-185).https:// to http:// in every *.list and *.sources file under /etc/apt (010-qemu.mk:244); see SSH logins and apt sources.power_state also sets message, timeout: 0 and condition: true; users is a list of two maps.xorriso -as genisoimage -volid cidata -joliet -rock -graft-points user-data=X.user-data meta-data=X.meta-data writes X.seed.iso.
%.seed.iso: %.user-data %.meta-data runs $(XORRISO) -as genisoimage -input-charset utf-8 -output $@ -volid cidata -joliet -rock -graft-points user-data=$(word 1,$^) meta-data=$(word 2,$^) (010-qemu.mk:268-278).XORRISO defaults to xorriso on the PATH, and make stops with "program xorriso is required" without it (000-garden.mk:20).clean removes *.seed.iso, *.meta-data and *.user-data (010-qemu.mk:300-302).X.seed.iso to X.ARCH.seed.iso, and the same for user-data and meta-data) remain for projects that used the names of image-garden 0.3 and 0.4 (010-qemu.mk:251-261).-joliet and -rock add the Joliet and Rock Ridge extensions, which keep long, lowercase file names that plain ISO 9660 would not.The provisioning boot adds -drive file=X.seed.iso,format=raw,readonly=true,media=cdrom on virtio-blk. The .run script never attaches the seed.
X.qcow2: <download> X.seed.iso X.efi-code.qcow2 X.efi-vars.qcow2; it runs qemu-img create -f qcow2 -b <download> -F qcow2 X.qcow2 64G, then the QEMU command line with -drive file=X.seed.iso,format=raw,id=drive1,if=none,readonly=true,media=cdrom -device virtio-blk,drive=drive1, piped through tee X.qcow2.log (rulegen.py:601-609). The BIOS and other architectures' rules attach the seed the same way..run script's storage option is only the overlay: -drive file=X.qcow2,…,media=disk … -device virtio-blk,drive=drive0,bootindex=0 (010-qemu-x86_64.mk:59-108).virtio-scsi-pci instead (050-ubuntu-core.mk:37-53); see Ubuntu Core images.X.qcow2, so make remakes both: see an edit rebuilds the images.Next: what the provisioning boot does, the users, SSH and apt, how a template is chosen, and the per-distribution quirks.
Read in mk/010-qemu.mk, mk/020-instances.mk, mk/050-ubuntu-core.mk, rulegen.py and data/*.ini of image-garden at the commit this map describes ("code"). The meta-data and host names in the table were produced by running image-garden make for those systems from an export of that commit, with GARDEN_ARCH=x86_64 and a project that defines the webserver instance ("run"). How cloud-init reads a NoCloud seed is cloud-init's behaviour, not image-garden's ("derived").
| File | Made by | Contents |
|---|---|---|
X.meta-data | echo through tee (rulegen.py:461-465) | the meta-data template with group and release |
X.user-data | echo through tee (rulegen.py:467-471) | the picked user-data template with group, user name and release |
X.seed.iso | xorriso -as genisoimage … -volid cidata (010-qemu.mk:268-278) | user-data and meta-data |
X.seed.iso, X.user-data, X.meta-data without the architecture | ln -sf (010-qemu.mk:251-261) | links kept for the names of image-garden 0.3 and 0.4 |
X is the system name with its architecture, such as ubuntu-cloud-24.04.x86_64. The seed is attached only to the provisioning boot (rulegen.py:601-609).
| System | instance-id | local-hostname and user-data hostname | user |
|---|---|---|---|
ubuntu-cloud-24.04.x86_64 | iid-ubuntu-24-04 | ubuntu-24-04 | ubuntu |
debian-cloud-13.x86_64 | iid-debian-13 | debian-13 | debian |
fedora-cloud-42.x86_64 | iid-fedora-42 | fedora-42 | fedora |
gentoo-cloud.x86_64 (no release) | iid-gentoo | gentoo | gentoo |
ubuntu-cloud-24.04@webserver.x86_64 | iid-ubuntu-24-04-webserver | ubuntu-24-04-webserver | ubuntu |
ubuntu-core-24+tpm.x86_64 | iid-ubuntu-core-24-tpm | ubuntu-core-24-tpm | ubuntu |
From 010-qemu.mk:94-106; $1 is the group, $2 the release and $3 a named instance's name. CLOUD_INIT_HOSTNAME makes the same name for the user-data:
CLOUD_INIT_HOSTNAME = $(subst +,-,$(subst .,-,$(strip $1$(if $(value 2),-$(value 2))$(if $(value 3),-$(value 3))))) #cloud-config instance-id: iid-$(call CLOUD_INIT_HOSTNAME,$1,$(value 2),$(value 3)) local-hostname: $(call CLOUD_INIT_HOSTNAME,$1,$(value 2),$(value 3))
CLOUD_INIT_META_DATA_TEMPLATE is set to it and may be redefined in .image-garden.mk.
BASE_CLOUD_INIT_USER_DATA_TEMPLATE, from 010-qemu.mk:187-247. $1 is the group, $2 the user name (the group again), $(value 3) the release and $(value 4) a named instance:
#cloud-config
timezone: Europe/Warsaw
power_state:
delay: now
mode: poweroff
message: Powering off
timeout: 0
condition: true
hostname: $(call CLOUD_INIT_HOSTNAME,$1,$(value 3),$(value 4))
ssh_pwauth: true
$(call EXTRA_CLOUD_INIT_APT_CONFIG,$1,$(value 3))
$(call PKGPROXY_CLOUD_INIT_BOOTCMD,$1)
users:
- name: root
plain_text_passwd: root
lock_passwd: false
shell: /bin/bash
- name: $2
groups: users
gecos: $2 User
plain_text_passwd: $2
sudo: ["ALL=(ALL) NOPASSWD:ALL"]
lock_passwd: false
shell: /bin/bash
write_files:
# Use /root/foo.APPEND in case /etc is a read-only fs.
- path: /root/sshd_config.APPEND
permissions: '0600'
content: |
# image-garden: allow interactive login with password authentication.
UsePam yes
# image-garden: allow root to log in over ssh.
PermitRootLogin yes
- path: /etc/cloud/cloud.cfg.d/99-image-garden.cfg
permissions: '0600'
content: |
# image-garden: allow interactive login with password authentication.
# Use only none and no-cloud data sources to avoid probing cloud-specific
# network services.
ssh_pwauth: true
# Instruct cloud-init not to look for cloud APIs.
datasource_list:
- NoCloud
- path: /root/hosts.APPEND
permissions: '0644'
content: |
# image-garden: ensure hostname resolves to localhost
127.0.0.1 $(call CLOUD_INIT_HOSTNAME,$1,$(value 3),$(value 4))
$(INJECTED_CLOUD_INIT_FILES)
$(call EXTRA_CLOUD_INIT_FILES,$1,$(value 3))
runcmd:
- cat /root/hosts.APPEND >> /etc/hosts
- rm -f /root/hosts.APPEND
- cat /root/sshd_config.APPEND >> /etc/ssh/sshd_config
- rm /root/sshd_config.APPEND
- sed -i -e 's/^PermitRootLogin prohibit-password/#PermitRootLogin prohibit-password/' /etc/ssh/sshd_config || true
- if [ -d /etc/apt ]; then find /etc/apt -type f \( -name '*.list' -o -name '*.sources' \) -exec sed -i -e 's|https://|http://|g' {} \; ; fi
$(call PKGPROXY_CLOUD_INIT_RUNCMD,$1)
- touch /etc/cloud/cloud-init.disabled
| Part | Deck |
|---|---|
power_state, touch /etc/cloud/cloud-init.disabled | Provisioning runs once |
users | The users every system gets |
ssh_pwauth, sshd_config.APPEND, 99-image-garden.cfg, the apt sed | SSH logins and apt sources |
EXTRA_CLOUD_INIT_APT_CONFIG, EXTRA_CLOUD_INIT_FILES | Changing what cloud-init does |
PKGPROXY_CLOUD_INIT_BOOTCMD, INJECTED_CLOUD_INIT_FILES, PKGPROXY_CLOUD_INIT_RUNCMD | What pkgproxy adds to user-data |
| replaced for Amazon Linux 2, Gentoo; apt hook for old Ubuntu | What differs per distribution |
| replaced for Ubuntu Core | Ubuntu Core images |
Four changes in the common user-data: SSH password logins, root logins, cloud-init limited to NoCloud, and apt sources moved to plain http.
ssh_pwauth: true (197), the SSH snippet with UsePam yes and PermitRootLogin yes (214-220), 99-image-garden.cfg with datasource_list: [NoCloud] (221-230), and the sed over /etc/apt (244).spread.yaml lists a user name and a password for each system, such as ubuntu/ubuntu (spread.yaml:60-72). The snapcraft, rockcraft and charmcraft components log in as system.users.0, which is root (snapcraft-vm:374-381).ssh_pwauth: true at the top and in 99-image-garden.cfg, plus UsePam yes in the SSH snippet. Then ssh -p PORT ubuntu@localhost takes the password ubuntu.
ssh_pwauth: true at the top level of the user-data (010-qemu.mk:197) and again in /etc/cloud/cloud.cfg.d/99-image-garden.cfg, written with mode 0600 (010-qemu.mk:221-230)./root/sshd_config.APPEND holds UsePam yes and PermitRootLogin yes (010-qemu.mk:214-220); the next scene follows it into /etc/ssh/sshd_config.allocate forwards 127.0.0.1:PORT to the guest's port 22 (image-garden:1105-1107); the port 5123 on the slide is an example from the range 5000 to 9999.ssh_pwauth: true makes cloud-init set PasswordAuthentication yes for the SSH server; sshd's keywords are case-insensitive, so UsePam is UsePAM.PermitRootLogin yes goes to /root/sshd_config.APPEND, then runcmd appends it to /etc/ssh/sshd_config and comments out PermitRootLogin prohibit-password.
write_files puts the snippet at /root/sshd_config.APPEND, mode 0600, under the comment "Use /root/foo.APPEND in case /etc is a read-only fs." (010-qemu.mk:213-220).runcmd then runs cat /root/sshd_config.APPEND >> /etc/ssh/sshd_config, rm /root/sshd_config.APPEND, and sed -i -e 's/^PermitRootLogin prohibit-password/#PermitRootLogin prohibit-password/' /etc/ssh/sshd_config || true (010-qemu.mk:241-243).sed changes only a line that starts with PermitRootLogin prohibit-password; a commented default is left alone. The line at the top of the panel is an example of what it changes, not the contents of a particular image./etc/cloud/cloud.cfg.d/99-image-garden.cfg sets datasource_list: [NoCloud] and ssh_pwauth: true for any later run of cloud-init.
write_files creates /etc/cloud/cloud.cfg.d/99-image-garden.cfg, mode 0600, with ssh_pwauth: true and datasource_list: [NoCloud], under the comments "Use only none and no-cloud data sources to avoid probing cloud-specific network services" and "Instruct cloud-init not to look for cloud APIs" (010-qemu.mk:221-230).runcmd command disables cloud-init for later boots (010-qemu.mk:246); see provisioning runs once. Removing /etc/cloud/cloud-init.disabled in a guest is one way cloud-init would run again (derived).write_files runs, so the file does not change the provisioning boot; files in cloud.cfg.d are read in name order, and 99- sorts late.datasource_list: [NoCloud] in its user-data instead (050-ubuntu-core.mk:131-133).find /etc/apt -type f \( -name '*.list' -o -name '*.sources' \) -exec sed -i -e 's|https://|http://|g' {} \;: plain http lets a proxy cache packages. Only https:// is replaced, so an inline key is left as it is.
runcmd command: if [ -d /etc/apt ]; then find /etc/apt -type f \( -name '*.list' -o -name '*.sources' \) -exec sed -i -e 's|https://|http://|g' {} \; ; fi (010-qemu.mk:244). It runs on every system and does nothing where there is no /etc/apt.https://, not https, because a deb822 .sources file may hold an inline armoured key, whose text can contain those letters (the reason given in the message of the commit that added .sources; NEWS says that guests with deb822 sources "fetch packages over http, so that pkgproxy can cache them", NEWS:33-34). The key lines on the slide are illustrative.snapcraft-vm also rewrites https://(archive|security|ports).ubuntu.com to http:// in *.sources and *.list under /etc/apt (snapcraft-vm:388-391); rockcraft-vm and charmcraft-vm run the same command. On a garden image those files are already rewritten.bootcmd on Debian and Ubuntu when a pkgproxy is reachable (010-qemu.mk:127-130); see what pkgproxy adds to user-data..sources files.Gentoo's template adds systemctl enable --now sshd.service; upstream spread cannot use its SSH. Ubuntu Core has only ubuntu/ubuntu.
mk/050.gentoo.mk: "Gentoo ships ssh disabled out of the box, so enable it.", and GENTOO_CLOUD_INIT_USER_DATA_TEMPLATE is the common template plus - systemctl enable --now sshd.service (050.gentoo.mk:4-8).ssh_pwauth: true and creates the user with useradd … --extrausers and chpasswd (050-ubuntu-core.mk:131-177); the README says "Ubuntu Core systems do not allow root password authentication" (README.md:708), and its --query lists only ubuntu (QUERY:40-53).sshd_config snippet and no apt command.Next: the users, allocate, the per-distribution quirks, pkgproxy, and safety.
Read in mk/010-qemu.mk, mk/050.gentoo.mk and mk/050-ubuntu-core.mk of image-garden at the commit this map describes and in bin/snapcraft-vm of snapcraft-gitlab-ci ("code"). What cloud-init, OpenSSH and apt do with these settings is their behaviour, not image-garden's ("derived").
| Setting | Where | When it acts |
|---|---|---|
ssh_pwauth: true | top level of the user-data (010-qemu.mk:197) | the provisioning boot |
UsePam yes, PermitRootLogin yes | /root/sshd_config.APPEND, appended to /etc/ssh/sshd_config by runcmd (010-qemu.mk:214-220, 010-qemu.mk:241-242) | from the next start of sshd (derived) |
#PermitRootLogin prohibit-password | sed over /etc/ssh/sshd_config (010-qemu.mk:243) | same |
ssh_pwauth: true, datasource_list: [NoCloud] | /etc/cloud/cloud.cfg.d/99-image-garden.cfg (010-qemu.mk:221-230) | any later run of cloud-init |
https:// to http:// | every *.list and *.sources file under /etc/apt (010-qemu.mk:244) | the next apt update (derived) |
| How | User | Password |
|---|---|---|
ssh -p PORT root@localhost, with the port allocate printed | root | root |
ssh -p PORT ubuntu@localhost | the group's name, such as ubuntu | the same word |
| Ubuntu Core | ubuntu | ubuntu |
allocate forwards 127.0.0.1:PORT to the guest's port 22 (image-garden:1105-1107). For tools, ./X.run --query prints the same users; see the users every system gets.
| System | Difference |
|---|---|
| Gentoo | systemctl enable --now sshd.service appended to runcmd (050.gentoo.mk:4-8); not usable with upstream spread (README.md:651-655) |
| Ubuntu Core | its own template: ssh_pwauth: true, user ubuntu in extrausers, no root password login (050-ubuntu-core.mk:131-177) |
systems without /etc/apt | the apt command does nothing |
A template is the whole user-data of a system. image-garden picks one per system: the most specific one defined.
PICK_CLOUD_INIT_USER_DATA_TEMPLATE_FOR returns the name of the first defined template, and the rule then calls that one (010-qemu.mk:280-298).The order: group, release and instance; group and instance; group and release; group; then the common CLOUD_INIT_USER_DATA_TEMPLATE.
$(or …) over the five names, each tested with $(value …), so the first defined one wins (010-qemu.mk:293-298).data/*.ini, the rule passes the group in capitals and the release, and no instance (rulegen.py:467); for a named instance it passes the instance too (020-instances.mk:75).CLOUD_INIT_USER_DATA_TEMPLATE, set to BASE_CLOUD_INIT_USER_DATA_TEMPLATE (010-qemu.mk:249).UBUNTU_24.04@webserver_CLOUD_INIT_USER_DATA_TEMPLATE: group in capitals, release with its dots, the instance after @. A misspelled name is never used, without a warning.
name.upper() (rulegen.py:47-48) and are passed to the picker with the release as written in the INI file (rulegen.py:467). The picker builds $1_$2@$(value 3)_CLOUD_INIT_USER_DATA_TEMPLATE and its shorter forms (010-qemu.mk:293-298).UBUNTU_24.04@webserver_CLOUD_INIT_USER_DATA_TEMPLATE and CENTOS@old-server_CLOUD_INIT_USER_DATA_TEMPLATE (README.md:1022-1044).@, which is kept as it is" (README.md:1024-1026), as the picker builds them.$(value …) and moves on when it is empty.Begin with $(CLOUD_INIT_USER_DATA_TEMPLATE). Dash lines right after it extend runcmd; a key such as packages: starts a new section.
power_state, the users, SSH settings and files, and ends with a runcmd: list whose last command disables cloud-init (010-qemu.mk:187-247); CLOUD_INIT_USER_DATA_TEMPLATE is that template (010-qemu.mk:249).$(CLOUD_INIT_USER_DATA_TEMPLATE), add a dash line after the comment "The template ends with runcmd:", then packages: (README.md:995-1020). Its notes: the default template "should always be included", and "You can assume the default template ends with a runcmd section and append your commands as a YAML list" (README.md:1061-1070).power_state cloud-init does not power the VM off, so the provisioning boot does not end and make waits for it.runcmd runs after touch /etc/cloud/cloud-init.disabled; that file stops later boots, not the current one.echo and build-essential lines are an example.Only one template is used. A release template can start from the group template to build on it, as image-garden's Debian template reuses its Ubuntu one.
.image-garden.mk defines UBUNTU_CLOUD_INIT_USER_DATA_TEMPLATE, ending in a packages: list, and sets DEBIAN_CLOUD_INIT_USER_DATA_TEMPLATE=$(UBUNTU_CLOUD_INIT_USER_DATA_TEMPLATE) (.image-garden.mk:43-58).$(UBUNTU_CLOUD_INIT_USER_DATA_TEMPLATE) expands the group template with the same arguments, as the Debian line does. What a following dash line extends depends on how that template ends: after the example group template, which ends in packages:, - libextra-dev is one more package. Illustrative, not run for this map.DEBIAN_13_CLOUD_INIT_USER_DATA_TEMPLATE (README.md:1000-1010).Next: named instances, several systems from one base image, and the hooks for smaller changes.
Read in mk/010-qemu.mk and the README of image-garden at the commit this map describes ("code").
For a system, the first template that is defined is used (010-qemu.mk:280-298):
| Order | Variable | Example for ubuntu-cloud-24.04@webserver.x86_64 |
|---|---|---|
| 1 | GROUP_RELEASE@INSTANCE_CLOUD_INIT_USER_DATA_TEMPLATE | UBUNTU_24.04@webserver_CLOUD_INIT_USER_DATA_TEMPLATE |
| 2 | GROUP@INSTANCE_CLOUD_INIT_USER_DATA_TEMPLATE | UBUNTU@webserver_CLOUD_INIT_USER_DATA_TEMPLATE |
| 3 | GROUP_RELEASE_CLOUD_INIT_USER_DATA_TEMPLATE | UBUNTU_24.04_CLOUD_INIT_USER_DATA_TEMPLATE |
| 4 | GROUP_CLOUD_INIT_USER_DATA_TEMPLATE | UBUNTU_CLOUD_INIT_USER_DATA_TEMPLATE |
| 5 | CLOUD_INIT_USER_DATA_TEMPLATE | the common template |
GROUP is the group in capitals; RELEASE keeps its dots. A template should start with $(CLOUD_INIT_USER_DATA_TEMPLATE), which ends with a runcmd: list you can append to (README "Local cloud-init Templates").
See several systems from one base image for worked examples.
| You want | Write |
|---|---|
| more commands | dash lines right after $(CLOUD_INIT_USER_DATA_TEMPLATE): they extend its runcmd: list |
| packages | a packages: key and a list |
| files | the EXTRA_CLOUD_INIT_FILES hook: a second write_files: key after the common template would, by the YAML rule that the last duplicate key wins, replace the common one (derived) |
| to build on the group template | start the release template with $(GROUP_CLOUD_INIT_USER_DATA_TEMPLATE) instead of the common one |
A template replaces every less specific one: nothing is merged. Every template must, directly or through another, start from $(CLOUD_INIT_USER_DATA_TEMPLATE), which creates the users, opens SSH and powers the machine off at the end of the provisioning boot. See changing what cloud-init does for the hooks.
Every cloud system gets root with password root and a user named after the distribution, such as ubuntu with password ubuntu.
users: list: root with plain_text_passwd: root, and $2, the group's name, with plain_text_passwd: $2 (010-qemu.mk:200-211).root/root for root account, distribution name (e.g., ubuntu/ubuntu) for user account" (README.md:25-31).ubuntu-24-04 for this system (010-qemu.mk:196).ubuntu user: see Ubuntu Core images.root: plain_text_passwd: root, lock_passwd: false, shell /bin/bash. SSH logins as root need the changes in the SSH deck.
name: root, plain_text_passwd: root, lock_passwd: false, shell: /bin/bash (010-qemu.mk:201-204).PermitRootLogin yes and password authentication, both set elsewhere in the same user-data (010-qemu.mk:197, 010-qemu.mk:214-220); see SSH logins and apt sources.lock_passwd: false leaves the account's password usable; cloud-init locks it by default.The second user is the group's name with the same password, in group users, with sudo: ["ALL=(ALL) NOPASSWD:ALL"] and bash.
name: $2, groups: users, gecos: $2 User, plain_text_passwd: $2, sudo: ["ALL=(ALL) NOPASSWD:ALL"], lock_passwd: false, shell: /bin/bash (010-qemu.mk:205-211).$2 is the group, passed twice by the user-data rule: once as the group and once as the user name (rulegen.py:467). The group is the Group= of the file's [META] section, such as Group=ubuntu (ubuntu.ini:4-6) or Group=debian (debian.ini:4-6).data/*.ini: almalinux, alpine, amazonlinux, archlinux, centos, debian, fedora, gentoo, opencloudos, opensuse, oracle, rocky, ubuntu. Each is also the user name and its password../ubuntu-cloud-24.04.x86_64.run --query prints system.users.0 root/root and system.users.1 ubuntu/ubuntu. Ubuntu Core lists only ubuntu.
--query preamble of every .run script prints vm.memory_mb, then the users: for root distro, system.users.0 is root/root and system.users.1 the group's name twice; for only:ubuntu, system.users.0 is ubuntu/ubuntu (010-qemu.mk:57-92).data/*.ini use root distro (query_users, rulegen.py:127), and so do their named instances (020-instances.mk:89); the Ubuntu Core launchers pass only:ubuntu (050-ubuntu-core.mk:23-26).snapcraft-vm reads system.users.0.username and .password from the query, logs in with sshpass, and sets sudo='sudo -H' unless the user is root (snapcraft-vm:374-381); rockcraft-vm and charmcraft-vm do the same.allocate runs memory_check on the .run script once make has made it, before it starts the machine (image-garden:1066-1068); memory_check reads vm.memory_mb and compares it with MemAvailable (image-garden:712-730).QEMU_MEM_OPTION when it is set; 2048 is the default (010-qemu.mk:9).The --query answers are fixed when the .run script is made, from the kind of system. A template that changes passwords does not change them.
--query answers are echo lines that make writes into the .run script; the users come from the third argument of EMIT_QEMU_RUN_SCRIPT_QUERY_PREAMBLE, root distro or only:ubuntu, and the group (010-qemu.mk:57-92)..run rule passes {img.query_users} and the group (rulegen.py:594-599); a named instance passes root distro and its base system's group (020-instances.mk:87-89). The .run rule does not depend on the user-data..run script or its rule reads the user-data, so a template that changes the users leaves --query as it was.s3cret is an example.Fixed passwords are a deliberate trade for testing. allocate forwards 127.0.0.1:PORT only; the .run script forwards nothing by default.
allocate sets QEMU_NETDEV_USER_EXTRA=",hostfwd=tcp:127.0.0.1:$PORT-:22" (image-garden:1105-1107)..run script's network is -netdev user,id=netdev0 plus QEMU_NETDEV_USER_EXTRA when you set it (010-qemu-x86_64.mk:8-11), so it forwards no host port by default.Next: SSH logins, allocate, spread's backend, safety, and templates.
Read in mk/010-qemu.mk, mk/050-ubuntu-core.mk, rulegen.py, data/*.ini and QUERY of image-garden at the commit this map describes, and in bin/snapcraft-vm of snapcraft-gitlab-ci ("code"). The user names per group are worked out from the template ("derived"). One run: the --query of a named instance, made with image-garden make from an export of that commit.
| Systems | Users | Passwords | sudo |
|---|---|---|---|
every system from data/*.ini, and their named instances | root, and the group's name | root, and the group's name | the group user: ALL=(ALL) NOPASSWD:ALL |
| Ubuntu Core | ubuntu | ubuntu | see Ubuntu Core images |
The common template's users: list (010-qemu.mk:200-211). A project template that starts from $(CLOUD_INIT_USER_DATA_TEMPLATE) keeps both accounts.
Group ([META] Group=) | User and password | Example system |
|---|---|---|
| almalinux | almalinux | almalinux-cloud-9.x86_64 |
| alpine | alpine | alpine-cloud-3.x86_64 |
| amazonlinux | amazonlinux | amazonlinux-cloud-2023.x86_64 |
| archlinux | archlinux | archlinux-cloud.x86_64 |
| centos | centos | centos-cloud-10.x86_64 |
| debian | debian | debian-cloud-13.x86_64 |
| fedora | fedora | fedora-cloud-42.x86_64 |
| gentoo | gentoo | gentoo-cloud.x86_64 |
| opencloudos | opencloudos | opencloudos-cloud-9.x86_64 |
| opensuse | opensuse | opensuse-cloud-16.0.x86_64 |
| oracle | oracle | oracle-cloud-9.x86_64 |
| rocky | rocky | rocky-cloud-10.x86_64 |
| ubuntu | ubuntu | ubuntu-cloud-24.04.x86_64 |
$ ./ubuntu-cloud-24.04.x86_64.run --query vm.memory_mb=2048 system.users.0.username=root system.users.0.password=root system.users.1.username=ubuntu system.users.1.password=ubuntu
From the QUERY file's example (QUERY:55-69) and the preamble that prints it (010-qemu.mk:57-92). The users are fixed when make writes the .run script; only vm.memory_mb follows the environment (QEMU_MEM_OPTION). A named instance's script prints its base system's users the same way: run for this map, ./amazonlinux-cloud-2@web.x86_64.run --query printed root/root and amazonlinux/amazonlinux.
The integrations only run image-garden and read its output. The craft components' tests replace it with a 30-line stand-in that answers allocate --spread, writes a .run that answers --query, and accepts discard.
allocate must be called with --spread, prints <ADDRESS localhost:5555> (or <FATAL …> and exit 213 with FAKE_ALLOCATE=fail), and writes .image-garden/SYSTEM.run, which prints system.users.0.username=ubuntu and system.users.0.password=ubuntu; discard does nothing (snapcraft-gitlab-ci testdata/bin/image-garden:6-30). It also logs PKGPROXY_URL, QEMU_MEM_OPTION and QEMU_SMP_OPTION, which the tests check.spread.yaml's garden backend runs allocate and discard (sp-adhoc).allocate --spread prints progress on stderr and one line on stdout, <ADDRESS localhost:PORT> or <FATAL …> with exit 213. SSH is forwarded on 127.0.0.1. discard takes only localhost:PORT.
--spread selects spread's protocol (image-garden:1023-1026). The make that prepares the system writes to stderr (>&2, image-garden:1063), as do the progress messages.hostfwd=tcp:127.0.0.1:PORT-:22 (image-garden:1104-1107), so whatever connects must run on the same host or in the same container.SSH- banner for up to GARDEN_SSH_WAIT_TIMEOUT seconds (600), then prints <ADDRESS localhost:PORT>; after the timeout it prints the address anyway. A machine that dies first, or a port probe that fails, gives <FATAL …> and exit 213, as does a QEMU that does not start (image-garden:1167-1216).sed -n -E 's/^<ADDRESS (.*)>$/\1/p' and take ${address##*:} as the port; without an address line the job fails with "image-garden printed no address" (snapcraft-vm:370-373).discard localhost:PORT kills the QEMU of that pid file and removes it; any other form exits 1; discard -a stops every machine of the user (image-garden:1221-1268). spread's garden backend calls it with exec and $SPREAD_SYSTEM_ADDRESS (spread.yaml:59).image-garden works in the current directory: .image-garden/ there holds the image, the .run script and the logs, and .image-garden.mk there is included. The craft scripts and the action rely on those paths.
GARDEN_PROJECT_DIR="$(pwd)" (image-garden:7); mk/999-local.mk has -include $(GARDEN_PROJECT_DIR)/.image-garden.mk (999-local.mk:5).SYSTEM.run and SYSTEM.qcow2 in .image-garden/ when it exists, otherwise in the current directory, and locks SYSTEM.lock there (image-garden:1057-1068); it starts ./SYSTEM.run from there, with SYSTEM.PORT.serial.log, .stdout.log and .stderr.log beside it (image-garden:1149-1160).$work/.image-garden, copy the image-garden-mk input to $work/.image-garden.mk, run allocate and discard from $work, read $work/.image-garden/SYSTEM.run --query and copy $work/.image-garden/*.log (snapcraft-vm:337-349, snapcraft-vm:282-286, snapcraft-vm:374).SUBDIR/.image-garden without *.log, keyed on the hash of SUBDIR/.image-garden.mk, and uploads .image-garden/*.log when the job fails (action.yaml:116-123, action.yaml:480-489).The craft scripts read system.users.0.username and .password from --query, and set QEMU_MEM_OPTION, QEMU_SMP_OPTION and PKGPROXY_URL; the runner or the action sets GARDEN_DL_PKGPROXY.
SYSTEM.run --query prints vm.memory_mb=N, from QEMU_MEM_OPTION or the default, and the users as system.users.N.username= and system.users.N.password= lines, then exits (010-qemu.mk:57-92). allocate itself reads vm.memory_mb for its memory check.system.users.0.username and system.users.0.password (snapcraft-vm:374-377)..run script uses QEMU_MEM_OPTION and QEMU_SMP_OPTION when set, word-split into QEMU's arguments (010-qemu-x86_64.mk:73-98); the craft scripts export -m MEMORY and -smp CPUS (snapcraft-vm:362-368).PKGPROXY_URL (http://host[:port]) is read when the image is made (010-qemu.mk:20-29). GARDEN_DL_PKGPROXY is read by the download helpers; at v0.8.0 it defaults to PKGPROXY_URL, or the snap's pkgproxy, and set but empty turns it off (image-garden:31-58). The action sets GARDEN_DL_PKGPROXY=http://127.0.0.1:3142 (action.yaml:391-393).--query preamble is EMIT_QEMU_RUN_SCRIPT_QUERY_PREAMBLE; rulegen.py passes root distro for cloud images, mk/050-ubuntu-core.mk passes only:ubuntu (rulegen.py:127, 050-ubuntu-core.mk:25). A new user model must keep user 0 able to log in with a password.The action relies on image-garden make of SYSTEM.ARCH .qcow2 .run .user-data .meta-data .seed.iso, rebase SYSTEM.ARCH.qcow2, the pkgproxy and spread-variant options, the pkgproxy-sockets plug and the image-garden.spread app.
image-garden make --debug --dry-run SYSTEM.$(uname -m).qcow2, then image-garden make of .qcow2, .run, .user-data, .meta-data and .seed.iso; with cache-prepared-images, image-garden rebase SYSTEM.$(uname -m).qcow2; it first creates ~/snap/image-garden/common/cache/dl (action.yaml:411-442).snap connect image-garden:pkgproxy-sockets pkgproxy:sockets, snap set image-garden pkgproxy=snap or pkgproxy=http://HOST-IP:3142, snap alias image-garden.spread spread, snap set image-garden spread-variant=… (action.yaml:376-401).spread app runs spread-chooser (snapcraft.yaml:211-224); the pkgproxy-sockets content plug (snapcraft.yaml:254-266); the configure hook accepts pkgproxy as component, snap, none or a URL (configure:11-36) and installs the spread component for spread-variant (configure:83-101)..image-garden/, takes the system name or the .qcow2 file name, and rewrites its backing path with qemu-img rebase -u (image-garden:943-980). The usage text, man page and README write rebase SYSTEM.ARCH; the action's .qcow2 form works the same.Renaming or reshaping any of these breaks an integration, and so can a change in behaviour: allocate's use of nc once cost ten minutes per VM on aarch64 runners. The GitLab components pin a container tag; the action follows a snap channel.
/dev/tcp (tcp_probe, image-garden:785-801); v0.7.1 used nc -w for both.FROM registry.gitlab.com/zygoon/image-garden:v0.7.2 (snapcraft-gitlab-ci Dockerfile:9), and each component's default image is its own image of the same version, so a new image-garden reaches a pipeline when it moves to a new component release.FROM image-garden:v0.7.0 (spread-gitlab-ci Dockerfile:20), before the nc fix; none of the four uses v0.8.0 yet.image-garden from image-garden-channel, latest/stable by default, in every job (action.yaml:12-14, action.yaml:366-375).--query, the .image-garden/ layout or the variables against the craft components' tests: their stand-in records exactly what they expect (snapcraft-gitlab-ci testdata/bin/image-garden), and the action's integration workflow runs real jobs (image-garden-action .github/workflows/integration-test.yaml).Next: allocate, the adhoc backend, the craft components, the GitHub action, --query and rebase.
Read in the integrations at the commits in integrations.commits and in image-garden at the commit in garden.commit ("code"). Which project relies on which item was read in their scripts and templates; that a change would break them is derived. Nothing was run for this page.
| Item | Where image-garden does it | craft components | spread-gitlab-ci | image-garden-action |
|---|---|---|---|---|
image-garden allocate --spread SYSTEM.ARCH | image-garden:996-1219 | called directly | through your spread.yaml | through your spread.yaml |
one stdout line <ADDRESS localhost:PORT>, progress on stderr | image-garden:1063, :1203 | parsed with sed | spread reads it | spread reads it |
<FATAL …> and exit 213 | image-garden:1181-1213 | the job fails with the line | spread reports it | spread reports it |
SSH forwarded on 127.0.0.1:PORT | image-garden:1107 | ssh -p PORT USER@localhost | spread connects there | spread connects there |
image-garden discard localhost:PORT | image-garden:1249-1268 | in the exit trap | the discard hook, with exec | the discard hook, with exec |
state in .image-garden/ of the current directory | image-garden:1058-1068, :1149-1162 | the scratch directory | your project | cached and uploaded |
.image-garden.mk in the current directory | image-garden:7, mk/999-local.mk:5 | the image-garden-mk input | your project | its hash keys the image cache |
SYSTEM.run --query: system.users.0.username, .password | mk/010-qemu.mk:57-92 | the login | no (credentials in spread.yaml) | no |
QEMU_MEM_OPTION, QEMU_SMP_OPTION | mk/010-qemu-x86_64.mk:73-74 and the other arches | the memory and cpus inputs | your environment | no |
PKGPROXY_URL | mk/010-qemu.mk:20-29 | exported from pkgproxy-url | the runner's environment | no (snap set image-garden pkgproxy=) |
GARDEN_DL_PKGPROXY | image-garden:31-58 | the runner's environment | the runner's environment | http://127.0.0.1:3142 |
image-garden make SYSTEM.ARCH.{qcow2,run,user-data,meta-data,seed.iso} | the generated rules | no | no | yes |
image-garden rebase SYSTEM.ARCH.qcow2 | image-garden:943-980 | no | no | with cache-prepared-images |
snap: pkgproxy, spread-variant, pkgproxy-sockets, image-garden.spread | snap/hooks/configure, snap/snapcraft.yaml | no | no | yes |
~/snap/image-garden/common/cache/dl | image-garden:20-29 | no | no | created before make |
| Integration | image-garden it uses | How a new release arrives |
|---|---|---|
snapcraft-gitlab-ci 91b5e29 | container v0.7.2 | a new component release |
rockcraft-gitlab-ci e8fd725 | container v0.7.2 | a new component release |
charmcraft-gitlab-ci 6fc8543 | container v0.7.2 | a new component release |
spread-gitlab-ci 3d522d4 | container v0.7.0 | a new component release |
image-garden-action 2891c7a | snap, image-garden-channel (latest/stable) | the next job |
nc.The README, image-garden's own spread.yaml and spread-demo/spread.yaml run exec image-garden in both hooks, so the <ADDRESS> and <FATAL> lines are the hook's own output and image-garden's exit status is the hook's (spread.yaml:45-59). rebase takes SYSTEM.ARCH and SYSTEM.ARCH.qcow2 alike; the action passes the second.
Each job downloads the cloud image, snapcraft, snaps, packages and Go modules again. The component keeps no cache between jobs; a pkgproxy on the runners' network serves them from its cache after the first time.
cache: key (templates/build.yml:115-157).The cloud image goes through GARDEN_DL_PKGPROXY, set on the runner. The VM's downloads follow pkgproxy-url: empty means the runner's PKGPROXY_URL, off means none; the URL is exported as PKGPROXY_URL for allocate.
GARDEN_DL_PKGPROXY (pkgproxy 0.12 or later)"; the VM downloads through it "when the job has a pkgproxy URL that the VM reaches", pkgproxy-url or the runner's PKGPROXY_URL, off for none (snapcraft-gitlab-ci README.md:213-219).pick_pkgproxy: empty takes $PKGPROXY_URL, off none; anything else must match http://HOST[:PORT] and loses a trailing slash (snapcraft-vm:215-229). The URL is exported as PKGPROXY_URL (or PKGPROXY_URL is unset) before image-garden allocate (snapcraft-vm:356-366).GARDEN_DL_PKGPROXY set, image-garden asks pkgproxy for files/v1/fetch?url=…&sha256=… and falls back to the origin (image-garden:281-327).GARDEN_DL_PKGPROXY defaults to PKGPROXY_URL (image-garden:31-38), so the URL the script exports would carry the image download too. The components' images are built on v0.7.2, which reads only GARDEN_DL_PKGPROXY; that is why the README asks the runner to set it.PKGPROXY_URL reaches the proxy: how a guest reaches pkgproxy.pkgproxy.lan on the slide is an example name for your pkgproxy machine.pkgproxy-url must be http://HOST[:PORT] at an address that routes from the job container, such as the pkgproxy machine's address on your network. host-gateway is the container's name, not the VM's.
host-gateway, Docker's bridge address, is not one: it is the job container's name for the machine, which the VM does not have, and in a VM with Docker in it, the VM's own bridge." (snapcraft-gitlab-ci README.md:218-224; the input's description says the same, templates/build.yml:93-99).PKGPROXY_URL, resolves it with getent ahostsv4 and writes that IPv4 address into the guest's /etc/hosts as pkgproxy; a host that does not resolve gives the warning cannot use pkgproxy at "…": want http://host[:port] with a host that resolves to IPv4; guests get no pkgproxy (010-qemu.mk:24-29).pkgproxy.lan on the slide is an example name.As root in the VM: Ubuntu's https:// archives become http://, then curl -fsSL URL/setup/TOOL | sh for each tool in pkgproxy-setup (apt snap go). snapcraft, snaps, packages and Go modules then come through pkgproxy.
sed over /etc/apt that turns https://archive.ubuntu.com, security.ubuntu.com and ports.ubuntu.com into http:// ("pkgproxy caches http:// archives only; an https:// one is a tunnel"), then curl -fsSL URL/setup/TOOL | sh for each tool (snapcraft-vm:388-398).pkgproxy-setup defaults to apt snap go; each name must match ^[a-z][a-z-]*$ (templates/build.yml:100-105, snapcraft-vm:307-309).PKGPROXY_URL was set: its cloud-init adds pkgproxy to /etc/hosts, runs the apt setup at bootcmd on Debian and Ubuntu and the snap setup at runcmd, and sets GOPROXY in /etc/environment (010-qemu.mk:127-180). The script's own run covers root's Go settings and the https archives.https:// into http:// in every .list and deb822 .sources file under /etc/apt, at the end of the first boot (010-qemu.mk:244). The components' images carry image-garden v0.7.2, whose rewrite covers .list files only (mk/010-qemu.mk:216 at the v0.7.2 tag), while Ubuntu 24.04 and later keep their archives in .sources; the script's sed is what switches those (derived).A malformed URL stops the job at once: cannot use the pkgproxy "…": its URL must be http://HOST[:PORT]. An unreachable one fails the pkgproxy section. Image downloads fall back to the origin; pkgproxy-url: off builds without.
^http://[^/:@[:space:]]+(:[0-9]+)?/?$ fails in the first section with snapcraft-vm: cannot use the pkgproxy "URL": its URL must be http://HOST[:PORT] (snapcraft-vm:215-229). So does an https:// URL.bash -c "set -euo pipefail; curl -fsSL URL/setup/TOOL | sh" in the VM, and snapcraft-vm runs with set -e, so a curl that cannot connect or resolve ends the job in the section "Setting the VM up for pkgproxy at URL" (snapcraft-vm:245-256, snapcraft-vm:388-398). Derived from the code, not run.pkgproxy-url: off builds with no pkgproxy, even when the runner sets PKGPROXY_URL (snapcraft-vm:215-221). The runner's GARDEN_DL_PKGPROXY still applies to the image download.Next: why pkgproxy, the runner's environment, how a guest reaches pkgproxy, image downloads, and the GitHub action's caches.
Include snapcraft-gitlab-ci/build@1 with the tag of a KVM runner: its job packs the snap in a throwaway Ubuntu VM of the snap's base. rockcraft- and charmcraft-gitlab-ci do the same for rocks and charms.
snapcraft pack --destructive-mode and copies the snaps back (snapcraft-gitlab-ci README.md:9-21).$CI_SERVER_FQDN/zygoon/snapcraft-gitlab-ci/build@1 with tags: [x86_64, kvm]; on a runner without /dev/kvm the job fails before it starts the VM (README.md:25-35).snapcraft-vm; its artifacts are the snaps, the components and snapcraft-vm-logs/, uploaded when: always (templates/build.yml:143-157).rockcraft-vm and charmcraft-gitlab-ci runs charmcraft-vm, the same script with RCV_ and CCV_ variables instead of SCV_. This deck quotes snapcraft-gitlab-ci at 91b5e29; rockcraft-gitlab-ci was read at e8fd725, charmcraft-gitlab-ci at 6fc8543.core24 picks ubuntu-cloud-24.04, and the runner's uname -m completes it: ubuntu-cloud-24.04.x86_64. The system input overrides the base; without /dev/kvm the job stops here.
build-base, or base, from the first of snap/snapcraft.yaml, snapcraft.yaml, .snapcraft.yaml and build-aux/snap/snapcraft.yaml it finds (snapcraft-vm:152-178).core20, core22, core24 and core26 map to ubuntu-cloud-20.04 … ubuntu-cloud-26.04; any other base fails with "cannot pick a system for the base … set the system input" (snapcraft-vm:180-189). snapcraft comes from latest/stable, or 8.x/stable for core20 (snapcraft-vm:191-198)..$SCV_ARCH, which defaults to uname -m (snapcraft-vm:64, snapcraft-vm:299-305). The snap is built for the runner's architecture.build-base, or base (a bare rock must set build-base), and maps ubuntu@20.04 to ubuntu@26.04 (and the deprecated ubuntu:20.04, ubuntu:22.04); devel needs the system input (rockcraft-vm:165-192). charmcraft-vm also looks in platforms and the legacy bases, and asks for the platform or system input when a charm has several (charmcraft-vm:174-228).A scratch directory under /var/tmp holds .image-garden/ and your .image-garden.mk; QEMU_MEM_OPTION and QEMU_SMP_OPTION size the VM; image-garden allocate --spread answers with <ADDRESS localhost:PORT>.
mktemp -d "${TMPDIR:-/var/tmp}"/snapcraft-vm.XXXXXX, unless SCV_WORK_DIR names one; the script creates .image-garden/ in it and copies the image-garden-mk input there as .image-garden.mk (snapcraft-vm:337-349).PKGPROXY_URL (or unsets it), QEMU_MEM_OPTION="-m $SCV_MEMORY" and QEMU_SMP_OPTION="-smp $SCV_CPUS", then runs (cd "$work" && image-garden allocate --spread "$system") and takes the address from the line <ADDRESS …>; without one it fails with "image-garden printed no address" (snapcraft-vm:356-373). The defaults are 2048 MiB and 2 CPUs; cpus: auto takes nproc, capped by the job cgroup's CPU quota (snapcraft-vm:125-150)..run and .qcow2 first, in .image-garden/ when that directory exists (image-garden:1057-1063); with --spread it prints <ADDRESS localhost:PORT> once the guest's SSH banner answers (image-garden:1167-1203)..image-garden/SYSTEM.run --query names system.users.0: root, password root, on Ubuntu cloud images. Every step is then ssh -p PORT root@localhost, its output streamed into the job log.
"$work"/.image-garden/"$system".run --query and reads system.users.0.username and system.users.0.password; with no user it fails with "its image names no user"; a user other than root gets sudo -H in front of every command (snapcraft-vm:374-381)..run script answers --query with vm.memory_mb=… and, for systems of rulegen.py's default root distro, system.users.0 root/root and system.users.1 the distribution's user with its own name as password (010-qemu.mk:57-90, rulegen.py:127). For ubuntu-cloud-24.04.x86_64 that is root/root, then ubuntu/ubuntu. Only Ubuntu Core systems report ubuntu first (only:ubuntu).SSHPASS=… sshpass -e ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -o LogLevel=ERROR -o ConnectTimeout=30 -o ServerAliveInterval=15 -o ServerAliveCountMax=8 -p PORT USER@localhost, without a terminal, so stdout and stderr stay apart (snapcraft-vm:231-256).== heading lines (snapcraft-vm:91-110)..run reports ubuntu/ubuntu as user 0 (testdata/bin/image-garden:20); the real cloud image reports root first.snapcraft is installed in the VM, the working tree streams in as tar over ssh (no .image-garden), snapcraft pack --destructive-mode runs there, and the snaps stream back into snaps/, named in a dotenv report.
snap wait system seed.loaded, then snap install snapcraft --classic --channel=…; when that fails, a folded section shows what the VM's network reaches before the job fails with "cannot install snapcraft in the VM" (snapcraft-vm:400-416).tar -cf - --no-wildcards --exclude=.image-garden --exclude=./OUTPUT …, followed by a second archive of what git tracks inside .image-garden directories, streamed uncompressed into /root/build in the VM; the job token is removed from origin's URL and git in the VM ignores snapcraft's work directories (snapcraft-vm:420-453).prepare input runs as root before the pack; then snapcraft pack --destructive-mode with --platform or --build-for and the snapcraft-args input (snapcraft-vm:455-467). Files the pack left that git does not ignore are listed, and fail the job with require-clean-tree: "true" (snapcraft-vm:469-482).*.snap and *.comp come back as a tar stream into output-dir (snaps); the dotenv report snapcraft-vm.env sets SNAP_FILE, SNAP_FILES, SNAP_VERSION and SNAP_COMPONENTS (snapcraft-vm:484-506; README.md:93-109).*.rock with rockcraft pack --destructive-mode (rockcraft-vm:447, rockcraft-vm:468-469); charmcraft-vm packs *.charm (charmcraft-vm:489, charmcraft-vm:510-511).An exit trap fetches snapcraft's logs, runs image-garden discard localhost:PORT, copies .image-garden/*.log into snapcraft-vm-logs/ and deletes the scratch directory. Artifacts are uploaded when: always.
trap cleanup EXIT, and trap 'exit 143' TERM HUP INT, so the cleanup also runs when the job is interrupted (snapcraft-vm:294-295)./root/.local/state/snapcraft/log out of the VM, runs (cd "$work" && image-garden discard "$address"), copies "$work"/.image-garden/*.log into the log directory ("The VM's serial console and qemu's output: what tells a VM that died inside from one killed from outside") and removes a work directory it made ("The VM's image is gigabytes: not left behind where nothing reuses it"); the exit status is the build's (snapcraft-vm:264-293).localhost:PORT, kills the QEMU named by its pid file and removes the pid file (image-garden:1254-1268). The logs it leaves are SYSTEM.PORT.serial.log, .stdout.log and .stderr.log from allocate (image-garden:1153-1160), and the provisioning boot's SYSTEM.qcow2.log.OUTPUT/*.snap, OUTPUT/*.comp and snapcraft-vm-logs/, when: always, kept for expire-in (1 week), and the dotenv report (templates/build.yml:145-157).Next: why the craft components keep no cache, KVM in CI, allocate, --query, the contract, and GitLab versus GitHub.
Read in snapcraft-gitlab-ci at 91b5e29, rockcraft-gitlab-ci at e8fd725 and charmcraft-gitlab-ci at 6fc8543 ("code"): templates/build.yml, bin/*craft-vm and the READMEs. What image-garden does in each step was read in image-garden v0.8.0; the components' images are built on image-garden v0.7.2. The user that --query reports for an Ubuntu cloud image is derived from rulegen.py's default. Nothing was run for this page.
.gitlab-ci.yml:
include: - component: $CI_SERVER_FQDN/zygoon/snapcraft-gitlab-ci/build@1 inputs: tags: [x86_64, kvm] memory: "4096" cpus: auto
| Step | What happens | snapcraft-vm |
|---|---|---|
| Resolve | base to system, .$(uname -m), pkgproxy URL, cpus, /dev/kvm check, work directory | :297-354 |
| Starting SYSTEM | PKGPROXY_URL, QEMU_MEM_OPTION, QEMU_SMP_OPTION; image-garden allocate --spread; <ADDRESS>; .run --query | :356-382 |
| The VM | /etc/os-release, uname -m, nproc, free -m in the guest | :384-386 |
| pkgproxy | https archives to http; curl URL/setup/TOOL piped to sh | :388-398 |
| snapcraft | snap wait system seed.loaded; snap install snapcraft --classic | :400-416 |
| Copying the source | tar over ssh into /root/build, no .image-garden | :418-453 |
| Preparing | the prepare input, as root | :455-460 |
| Packing | snapcraft pack --destructive-mode | :462-482 |
| Copying the snaps out | tar back into output-dir; dotenv | :484-508 |
| Discarding | logs, image-garden discard, .image-garden/*.log, rm -rf the work directory | :264-295 |
rockcraft-vm and charmcraft-vm have the same steps, about 20 lines earlier and 20 lines later respectively.
The three templates share these inputs; the variable prefix is SCV_, RCV_ or CCV_.
| Input | Default | Meaning |
|---|---|---|
job-name, stage | snap-build (rock-build, charm-build), build | the job |
image | the component's own image, same version | must have image-garden, ssh, sshpass and the script |
tags | [] | runners that give jobs /dev/kvm |
timeout | 1h | the job's timeout |
project-dir | . | where the project's yaml file is |
system | empty | the image-garden system; empty picks it from the base |
memory | 2048 | the VM's memory in MiB, as QEMU_MEM_OPTION |
cpus | 2 | the VM's CPUs, or auto, as QEMU_SMP_OPTION |
prepare | empty | shell run as root in the VM before the pack |
require-clean-tree | "false" | fail when the pack leaves untracked files |
image-garden-mk | empty | an .image-garden.mk for the VM's image |
pkgproxy-url | empty | http://HOST[:PORT]; empty for the runner's PKGPROXY_URL, off for none |
pkgproxy-setup | apt snap go | pkgproxy setup scripts the VM runs |
output-dir | snaps (rocks, charms) | where the packed files go |
expire-in | 1 week | how long artifacts are kept |
Sources: snapcraft-gitlab-ci templates/build.yml:13-113, and the same file in rockcraft-gitlab-ci and charmcraft-gitlab-ci. Each component also has its own inputs, such as snapcraft-channel and platform.
| snapcraft base | rockcraft and charmcraft build base | system |
|---|---|---|
core20 | ubuntu@20.04 | ubuntu-cloud-20.04 |
core22 | ubuntu@22.04 | ubuntu-cloud-22.04 |
core24 | ubuntu@24.04 | ubuntu-cloud-24.04 |
core26 | ubuntu@26.04 | ubuntu-cloud-26.04 |
Then .$(uname -m) is appended, unless the system already ends in an architecture.
zyga/image-garden-action installs image-garden on a GitHub runner and runs your spread tests on one garden system per job.
spread, on vanilla images" prepared by image-garden (image-garden-action README.md:7-17).One job per system: actions/checkout with fetch-depth: 0, then zyga/image-garden-action@v0 with garden-system. The other inputs are optional.
actions/checkout with fetch-depth: 0 ("essential for git restore-mtime to work correctly"), then zyga/image-garden-action@v0 with garden-system (image-garden-action README.md:405-432).garden-system is required; spread-variant, spread-live, spread-subdir, spread-backend (garden), spread-tasks, spread-artifacts; the cache inputs cache-prepared-images, save-cache, save-package-cache, cache-scope, cache-key-prefix; and the three snap channels..image-garden.mk, the action runs git restore-mtime on it, so make sees when it last changed in git, not when it was checked out; without the history it warns "check out with fetch-depth: 0" (image-garden-action action.yaml:124-152).The action makes /dev/kvm usable, installs snapd and the pkgproxy snap (unless port 3142 is taken), then snap install --devmode image-garden.
/dev/kvm: sudo chmod -v 666 /dev/kvm when it exists, otherwise a notice and no hardware acceleration (image-garden-action action.yaml:153-160). There is no udev rule.snapd-channel, pkgproxy from pkgproxy-channel (image-garden-action action.yaml:227-232).sudo snap install --devmode --channel=… image-garden; snapd downloads the snap, its base and the components its hooks install through pkgproxy (image-garden-action action.yaml:370-375).+qemu-<arch> and +pkgproxy (install:6-14).snap set image-garden pkgproxy=snap after snap connect image-garden:pkgproxy-sockets pkgproxy:sockets, or pkgproxy=http://HOST-IP:3142; plus GARDEN_DL_PKGPROXY=http://127.0.0.1:3142.
snap connect image-garden:pkgproxy-sockets pkgproxy:sockets and snap set image-garden pkgproxy=snap. External mode: snap set image-garden pkgproxy=http://<first address of hostname -I>:3142, because 127.0.0.1 would be the guest itself (image-garden-action action.yaml:376-390). HOST-IP on the slide stands for that address.GARDEN_DL_PKGPROXY=http://127.0.0.1:3142 goes into the job's environment, so image-garden downloads pristine images through pkgproxy by their checksum (image-garden-action action.yaml:391-393).pkgproxy=snap and a URL each set what the guests' cloud-init and QEMU are given (010-qemu.mk:20-44); GARDEN_DL_PKGPROXY names the pkgproxy for image downloads (image-garden:31-58).image-garden make SYSTEM.$(uname -m).qcow2 …, then spread -v garden:SYSTEM:TASKS. Uploaded: spread.log always, artifacts, and .image-garden/*.log on failure.
snap alias image-garden.spread spread, and snap set image-garden spread-variant=… when the input is set (image-garden-action action.yaml:394-401).spread-subdir, a dry run, then image-garden make of SYSTEM.$(uname -m) .qcow2, .run, .user-data, .meta-data and .seed.iso, with the first boot folded in the log (image-garden-action action.yaml:412-435). With cache-prepared-images it also runs image-garden rebase SYSTEM.$(uname -m).qcow2 (image-garden-action action.yaml:436-442).spread [-artifacts DIR] -v [-live] BACKEND:SYSTEM:TASKS, piped through tee spread.log; the exit status is spread's (image-garden-action action.yaml:443-464).spread.log always; artifacts with every : renamed to _; .image-garden/*.log when the job failed (image-garden-action action.yaml:465-489).Two GitHub caches hold pkgproxy's cache: images per garden system, and packages per cache-scope. save-cache defaults to default-branch; cache-prepared-images is opt-in.
runner.arch and garden-system, and packages (everything else), keyed per cache-scope, which defaults to the garden system (image-garden-action action.yaml:189-208; image-garden-action README.md:160-176).save-cache is default-branch (default), always or never (image-garden-action action.yaml:21-23); pull requests and other branches restore the default branch's cache but never save their own; failed and cancelled jobs save too; each part is saved only when the job added to it (image-garden-action README.md:188-197).cache-prepared-images caches .image-garden/ itself, keyed on the hash of .image-garden.mk (image-garden-action action.yaml:116-123).pkgproxy-cache in the action).Next: the action's caches, why pkgproxy, the pkgproxy setting, spread variants and GitLab versus GitHub.
A runner starts empty. The action keeps pkgproxy's cache, which holds every download, in the GitHub cache by default; the prepared image only with cache-prepared-images.
.image-garden.mk are not part of either: see cache-prepared-images" (README.md:173-174); that input defaults to "false" (action.yaml:18-20).files/, the pristine images, is one GitHub cache per runner.arch and garden-system; everything else is another, per cache-scope. A matrix shares one scope and lets one job save it.
pkgproxy-cache splits /var/snap/pkgproxy/common/cache: "images: the pristine images that image-garden downloads, which pkgproxy keeps by checksum under files/, cached per garden system; packages: everything else: snaps, apt, docker, lxd and go, which jobs of a matrix can share" (pkgproxy-cache:5-12, pkgproxy-cache:37).PREFIX-images-RUNNER_ARCH-GARDEN_SYSTEM-RUN_ID-RUN_ATTEMPT and PREFIX-packages-RUNNER_ARCH-SCOPE-RUN_ID-RUN_ATTEMPT, where SCOPE is cache-scope or else garden-system; each is restored by the key without the run's part (action.yaml:189-208). PREFIX is cache-key-prefix, image-garden-pkgproxy-v1 by default; change it to start empty, as pkgproxy never deletes on its own (README.md:105-110).cache-scope: shared, one canary job saves, the others save-package-cache: "false"; "Every job then restores the shared packages and its own images, and saves its own images when they change" (README.md:199-227).X64 on the slide is GitHub's runner.arch for an x86-64 runner (GitHub's naming, not from these trees); shared is the README's example scope.The pkgproxy snap is installed and stopped, both archives are unpacked with --xattrs --xattrs-include='user.*', each part is fingerprinted, and pkgproxy starts. actions/cache alone would drop the attributes.
snap stop pkgproxy, gives it its settings in one snap set, then for images and packages runs sudo tar --xattrs --xattrs-include='user.*' -xf ARCHIVE -C /var/snap/pkgproxy/common/cache, records pkgproxy-cache fingerprint of each part and the usage table, and starts pkgproxy (action.yaml:231-238, action.yaml:304-322).actions/cache/restore into $RUNNER_TEMP/image-garden-pkgproxy/ (action.yaml:193-208).snap set per setting went over systemd's start limit (action.yaml:235-237, action.yaml:294-303).save-cache decides who may save; pkgproxy is stopped; each part's fingerprint, the sorted paths and sizes hashed, is compared with the one from the start; only a changed part is saved, under a key ending in the run ID and attempt.
always() in snap mode. save-cache: always saves; default-branch saves only when GITHUB_REF is the default branch, otherwise "only the default branch saves (save-cache: default-branch)"; never does not (action.yaml:545-601). "Failed and cancelled jobs save too, as whatever pkgproxy cached is valid."packages when save-package-cache is not true; compares pkgproxy-cache fingerprint with the one taken at the start; "Not saving the pkgproxy cache of images: nothing was added to it", or archives the part and marks it for saving (action.yaml:602-620).find … -type f -printf '%P %s\n' | sort | sha256sum, over files/ for images and over everything else except stats.json for packages (pkgproxy-cache:63-73). A file whose size changed counts; one rewritten at the same size does not.${{ github.run_id }}-${{ github.run_attempt }}, and the restore step's restore-keys is the key without them (action.yaml:193-208, action.yaml:621-634). That a prefix match restores the most recent cache is actions/cache's behaviour (derived, not in these trees).images-cache-saved and package-cache-saved report it (action.yaml:635-656).cache-prepared-images: true caches .image-garden/ without logs, keyed by system and hashFiles('.image-garden.mk'). git restore-mtime gives .image-garden.mk its last commit's time, so make keeps the image; it needs fetch-depth: 0.
actions/cache of SUBDIR/.image-garden and !SUBDIR/.image-garden/*.log, key image-garden-img-GARDEN_SYSTEM-HASH, where HASH is hashFiles('SUBDIR/.image-garden.mk') (action.yaml:116-123). The key has no architecture and no image-garden version in it. The README: "This uses a lot of cache storage and scales poorly with the number of systems" (README.md:71-77)..image-garden.mk exists, the action installs git-restore-mtime and runs git restore-mtime .image-garden.mk, with git whatchanged aliased to git log --raw --no-merges for newer git; when the file is not found in the history it warns "Cannot restore the mtime of .image-garden.mk from git history; check out with fetch-depth: 0" (action.yaml:124-152). This runs whether or not prepared images are cached.SYSTEM.user-data depends on $(MAKEFILE_LIST) and .image-garden.mk (rulegen.py:467-471); %.seed.iso on the user-data and meta-data (010-qemu.mk:268); SYSTEM.qcow2 on the downloaded base image and the seed (rulegen.py:601-602).fetch-depth: 0, "essential for git restore-mtime to work correctly" (README.md:405-432).SYSTEM.qcow2 also depends on the downloaded base image in the snap's download directory, outside .image-garden/. On a new runner that image is downloaded again, from pkgproxy, and gets the time of that download, newer than a restored prepared image; image-garden's downloads do not keep the server's file time. If that holds, make provisions the image again even on a cache hit.After make, image-garden rebase SYSTEM.$(uname -m).qcow2 finds the backing image by name in GARDEN_DL_DIR and runs qemu-img rebase. It runs whenever cache-prepared-images is true.
qemu-img create -f qcow2 -b $(GARDEN_DL_DIR)/GROUP/SYSTEM.qcow2 -F qcow2, so it names its base by that path (rulegen.py:601-604)..image-garden/ when that exists, reads full-backing-filename from qemu-img info, finds a file of that base name under GARDEN_DL_DIR, prints "image-garden: re-basing IMAGE on top of NEW" and runs qemu-img rebase -u -b NEW -F qcow2 IMAGE, which rewrites the path without opening the old base; it fails with "cannot find the backing image of …" when the download is not there (image-garden:943-980).image-garden make, in spread-subdir, as image-garden rebase GARDEN_SYSTEM.$(uname -m).qcow2 (action.yaml:411-442).cache-prepared-images is true; a TODO says it should run only on a hit (action.yaml:436-442). On a miss make has just built the image against this runner's download, so the rebase changes nothing..qcow2 file name alike; the action passes the .qcow2 form.Next: the GitHub action, why pkgproxy, rebase, the overlay, and GitLab versus GitHub.
Read in image-garden-action at 2891c7a ("code"): action.yaml, pkgproxy-cache and the README, and in image-garden at the commit in garden.commit for make's dependencies and rebase. How actions/cache matches restore keys is GitHub's behaviour, not in these trees ("derived"). Nothing was run for this page.
| Cache | Path | Key | Restored by | Saved when |
|---|---|---|---|---|
| pkgproxy images | $RUNNER_TEMP/image-garden-pkgproxy/images.tar (files/ of pkgproxy's cache) | PREFIX-images-ARCH-SYSTEM-RUN_ID-RUN_ATTEMPT | PREFIX-images-ARCH-SYSTEM- | snap mode, the policy allows, the fingerprint changed |
| pkgproxy packages | $RUNNER_TEMP/image-garden-pkgproxy/packages.tar (the rest) | PREFIX-packages-ARCH-SCOPE-RUN_ID-RUN_ATTEMPT | PREFIX-packages-ARCH-SCOPE- | as above, and save-package-cache is true |
| prepared images | SUBDIR/.image-garden, without *.log | image-garden-img-SYSTEM-HASH | the exact key | cache-prepared-images is true (actions/cache saves after the job) |
PREFIX is cache-key-prefix; ARCH is runner.arch; SYSTEM is garden-system; SCOPE is cache-scope, or garden-system when empty; HASH is hashFiles('SUBDIR/.image-garden.mk'). Sources: action.yaml:116-123, action.yaml:189-208, action.yaml:545-634.
| Input | Default | Meaning |
|---|---|---|
save-cache | default-branch | which runs save the pkgproxy cache: default-branch, always or never; anything else fails the job |
save-package-cache | "true" | whether this job saves the packages part; "false" in all but one job of a shared scope |
cache-scope | "" (the garden system) | the scope of the packages part |
cache-key-prefix | image-garden-pkgproxy-v1 | change it to start from an empty cache |
cache-prepared-images | "false" | also cache .image-garden/ and rebase the image |
Source: action.yaml:18-32, action.yaml:96-115.
| Output | Value |
|---|---|
pkgproxy-mode | snap, or external when a pkgproxy already listened on port 3142 |
images-cache-restored-key, package-cache-restored-key | the key restored from; empty on a cold start and in external mode |
images-cache-saved, package-cache-saved | true when the key exists after saving |
Source: action.yaml:57-72.
| When | Step |
|---|---|
| start | restore prepared images (opt-in); restore .image-garden.mk's time; detect pkgproxy; restore the two archives |
| setup | install snapd and pkgproxy; stop it; unpack the archives with user.* attributes; fingerprint; start it |
| work | install image-garden; image-garden make; image-garden rebase (opt-in); spread |
| end, always | stop pkgproxy; fingerprint; archive the parts that changed; save; check the keys exist; start pkgproxy again |
| after the job | actions/cache saves the prepared images, when that input is on |
jobs: canary: steps: - uses: zyga/image-garden-action@v0 with: garden-system: ubuntu-cloud-24.04 cache-scope: shared test: needs: canary strategy: matrix: garden-system: [debian-cloud-13, fedora-cloud-44] steps: - uses: zyga/image-garden-action@v0 with: garden-system: ${{ matrix.garden-system }} cache-scope: shared save-package-cache: "false"
From README.md:199-227.
spread-gitlab-ci on GitLab and image-garden-action on GitHub run the same spread.yaml, with the same allocate and discard. They differ in four ways: where image-garden comes from, KVM, pkgproxy and what persists.
spread with the backend input, garden by default (spread.yml:27-31); image-garden-action runs spread with spread-backend, also garden by default, and the required garden-system (action.yaml:42-47).type: adhoc backend of your spread.yaml, whose hooks run image-garden allocate --spread and image-garden discard (README.md:740-751).GitLab: an image built FROM the image-garden container at a tag, with spread added; nothing is installed in the job. GitHub: snapd, pkgproxy and the image-garden snap installed in every job, from latest/stable unless a channel input says otherwise.
FROM registry.gitlab.com/zygoon/image-garden:v0.7.0 with checksum-pinned spread, spread-plus and spread-gitlab-report added (spread-gitlab-ci Dockerfile:20-52); the component's default image is its own image of the same version (spread.yml:18-22). The craft components build on v0.7.2.snapd-channel, installs the pkgproxy snap from pkgproxy-channel and the image-garden snap, in devmode, from image-garden-channel, all latest/stable by default, and aliases image-garden.spread as spread (action.yaml:9-17, action.yaml:209-232, action.yaml:366-397).GitLab: your own runners with devices = ["/dev/kvm"], picked with tags. GitHub: the action runs chmod 666 /dev/kvm when the device exists, and otherwise continues, emulated.
/dev/kvm, so run image-garden jobs on runners of your own that pass the device into the job's container (devices = ["/dev/kvm"] in the docker executor's config.toml), and pick them with tags" (README.md:778-787).sudo chmod -v 666 /dev/kvm when it exists, otherwise the notice "/dev/kvm is not available, continuing without hardware acceleration" (action.yaml:153-160); without it, tests are "much, much slower" (README.md:367-373).GitLab: a long-lived pkgproxy named by PKGPROXY_URL, reached by its address. GitHub: the pkgproxy snap on the runner, pkgproxy=snap, reached through QEMU's guestfwd to its socket; or an existing one on port 3142 by URL.
PKGPROXY_URL set, image-garden resolves its host to IPv4 and the guest connects there; otherwise, with the sockets of the bundled pkgproxy or of a pkgproxy snap, QEMU gets guestfwd=tcp:10.0.2.100:3142-unix:…/pkgproxy.sock (010-qemu.mk:20-44).image-garden:pkgproxy-sockets and sets pkgproxy=snap, or sets pkgproxy=http://HOST-IP:3142 (action.yaml:376-393). setup-pkgproxy must come before the action (README.md:229-239).pkgproxy-url or the runner's PKGPROXY_URL: the craft components' pkgproxy.GitLab: jobs keep nothing but spread's rerun list; pkgproxy's cache stays on its own machine. GitHub: the action saves pkgproxy's cache in two GitHub caches and restores it; prepared images are opt-in.
cache:; spread-gitlab-ci's only cache is .spread-rerun/, keyed per pipeline and job (spread.yml:115-121).Next: spread-gitlab-ci, KVM in CI, the GitHub action, its caches, the craft components' pkgproxy and the snap's pkgproxy setting.
Read in spread-gitlab-ci at 3d522d4, the craft components at the commits in integrations.commits, image-garden-action at 2891c7a and image-garden v0.8.0 ("code"). Nothing was run for this page.
| Question | GitLab (spread-gitlab-ci, craft components) | GitHub (image-garden-action) |
|---|---|---|
| Where the job runs | in a container image built FROM the image-garden container | on a fresh Ubuntu runner |
| image-garden | the container at a fixed tag (v0.7.0 or v0.7.2) | the snap, image-garden-channel, latest/stable by default, installed every job |
| spread | added to the image by spread-gitlab-ci | the snap's spread component, aliased as spread |
| KVM | your own runners, devices = ["/dev/kvm"], picked with tags | chmod 666 /dev/kvm when present; otherwise emulated |
| pkgproxy | a long-lived pkgproxy, PKGPROXY_URL (and GARDEN_DL_PKGPROXY) in the runner's environment | the pkgproxy snap on the runner, pkgproxy=snap; or an existing one on port 3142 by URL |
| How a guest reaches it | the URL's host, resolved to IPv4, through QEMU's user network | guestfwd from 10.0.2.100:3142 to pkgproxy's socket |
| What persists | pkgproxy's own disk; spread-gitlab-ci's rerun list | pkgproxy's cache in two GitHub caches; prepared images opt-in |
| A new image-garden release | when the component's image moves to it | in the next job |
Sources: the image-garden README's CI section, 010-qemu.mk:20-44, spread-gitlab-ci Dockerfile:20-52, image-garden-action action.yaml.
Five projects run image-garden in CI: four GitLab CI components on the container, one GitHub action on the snap.
/dev/kvm for full speed; without it QEMU emulates the CPU, many times slower. GitLab.com's hosted runners do not give jobs /dev/kvm, so image-garden jobs, and every job built on it, run on runners of your own that pass the device in (README.md:778-787).91b5e29, rockcraft-gitlab-ci e8fd725, charmcraft-gitlab-ci 6fc8543, spread-gitlab-ci 3d522d4, image-garden-action 2891c7a (integrations.commits in this map's repository).snapcraft-, rockcraft- and charmcraft-gitlab-ci pack in a throwaway VM; spread-gitlab-ci runs your spread.yaml. Each image is built FROM the image-garden container.
FROM registry.gitlab.com/zygoon/image-garden:v0.7.2 in snapcraft-gitlab-ci (snapcraft-gitlab-ci Dockerfile:9), rockcraft-gitlab-ci (rockcraft-gitlab-ci Dockerfile:9) and charmcraft-gitlab-ci (charmcraft-gitlab-ci Dockerfile:15); spread-gitlab-ci still starts from v0.7.0 (spread-gitlab-ci Dockerfile:20).*craft-vm script; charmcraft-gitlab-ci also bundles charmcraft and skopeo for publishing. spread-gitlab-ci adds checksum-pinned spread, spread-plus and spread-gitlab-report, which turns spread's output into JUnit and annotations for GitLab (spread-gitlab-ci Dockerfile:22-51).image-garden allocate --spread, copy the project in with tar over ssh, run pack --destructive-mode inside, and copy the result back (snapcraft-gitlab-ci bin/snapcraft-vm).image-garden-action installs snapd, pkgproxy and the image-garden snap on the GitHub runner, then runs the snap's spread on one garden system.
image-garden.spread as spread (image-garden-action action.yaml:394-397).garden-system is its only required input (image-garden-action action.yaml:42-44).latest/stable (image-garden-action action.yaml:9-17).All five use allocate, its <ADDRESS> line, --query or spread's credentials, and discard. pkgproxy is their only cache between jobs.
image-garden allocate --spread prints <ADDRESS localhost:PORT> once SSH answers (image-garden:1203).SYSTEM.run --query prints the system's users and passwords (010-qemu.mk:63-92); the craft scripts read system.users.0.username and .password from it.Next: spread-gitlab-ci, image-garden-action, the craft components, the contract, pkgproxy and KVM runners.
Include the component and your pipeline gets a spread job: failed tasks in the merge request and test report, a page per failure, a folded log, and a stop before the timeout.
gitlab.com/zygoon/spread-gitlab-ci/spread@0.4.0 with systems and tags (README.md:25-31).systems input's description name fedora-42 (README.md:29, spread.yml:33-36); image-garden's system is fedora-cloud-42. The slides use image-garden's name.3d522d4.registry.gitlab.com/zygoon/spread-gitlab-ci is image-garden's image plus spread, spread-plus and spread-gitlab-report, pinned by checksum, for amd64 and arm64. Pick KVM runners with tags.
FROM registry.gitlab.com/zygoon/image-garden:v0.7.0 and adds spread (canonical/spread 32cad07, as spread-dist builds it), spread-plus (2ff7bdb3) and spread-gitlab-report v0.3.0, each with ADD --checksum, for amd64 and arm64 (Dockerfile:6-52).registry.gitlab.com/zygoon/spread-gitlab-ci:0.4.0, the component's own version (spread.yml:18-22)./dev/kvm, picked with tags; GitLab.com's hosted runners do not (README.md:38-50).The job runs spread with the garden backend; your spread.yaml defines it, with allocate and discard calling image-garden inside the job.
backend input defaults to garden; the job builds selectors from it and runs spread, or spread-VARIANT (spread.yml:27-31, spread.yml:126-151).garden backend is your spread.yaml's, type: adhoc, with allocate: exec image-garden allocate --spread "$SPREAD_SYSTEM"."$(uname -m)" and discard: exec image-garden discard "$SPREAD_SYSTEM_ADDRESS", as image-garden's README shows (README.md:740-751).127.0.0.1 inside the job container, where spread runs too.tags for KVM runners; systems and tests become selectors garden:SYSTEM:TEST; spread-variant: plus; spread-args; before-script.
tags [], backend garden, systems and tests empty for all, spread-args, spread-variant "" or plus, spread, before-script (spread.yml:10-92).backend:system:test, leaving out the parts not given; with none it passes no selector (spread.yml:126-138, README.md:33-36).spread, or spread-plus when spread-variant is plus, unless the spread input names another (spread.yml:146-147).timeout 2h, stop-before 10m, kill-after 5m. Up to two retries; rerun.txt, kept in the job's cache, narrows each retry to the tasks that did not pass.
timeout 2h, stop-before 10m, kill-after 5m: spread is stopped stop-before the timeout so that it restores its machines and the reports are uploaded (spread.yml:76-86).retry: max: retries (default 2, GitLab's limit) when: script_failure (spread.yml:100-103).junit.xml, annotations.json and rerun.txt; the job copies rerun.txt to .spread-rerun/selectors, kept in the cache spread-rerun-$CI_PIPELINE_ID-$CI_JOB_NAME_SLUG even when the job fails, and a retry runs only those tasks (spread.yml:115-169).Next: the adhoc backend, spread names, the container in CI, the GitHub action, the contract, and spread in the snap.
Read in spread-gitlab-ci at commit 3d522d4 ("code"): its README, templates/spread.yml and Dockerfile. The example was not run for this map.
.gitlab-ci.yml:
include: - component: gitlab.com/zygoon/spread-gitlab-ci/spread@0.4.0 inputs: systems: ubuntu-cloud-24.04 fedora-cloud-42 tags: [kvm, x86_64]
spread.yaml, the backend the job runs:
backends: garden: type: adhoc allocate: exec image-garden allocate --spread "$SPREAD_SYSTEM"."$(uname -m)" discard: exec image-garden discard "$SPREAD_SYSTEM_ADDRESS" systems: - ubuntu-cloud-24.04: username: ubuntu password: ubuntu - fedora-cloud-42: username: fedora password: fedora
| Input | Default | Meaning |
|---|---|---|
systems | all | systems, separated by spaces, as spread names them |
tests | all | suites or tasks, separated by spaces |
backend | garden | the spread backend; empty for every backend |
tags | [] | runner tags: pick runners with /dev/kvm |
spread-variant | empty | plus runs spread-plus |
spread-args | empty | more spread options, such as -v |
before-script | [] | commands to run before spread |
timeout | 2h | the job's timeout |
stop-before | 10m | stop spread this long before the timeout |
kill-after | 5m | kill spread this long after asking it to stop |
retries | 2 | GitLab retries of a failed job: 0, 1 or 2 |
rerun | true | a retry runs only the tasks that did not pass |
report-dir | spread-report | where the reports go |
image | registry.gitlab.com/zygoon/spread-gitlab-ci:0.4.0 | the job's image |
The full list, with job-name, stage, spread and expire-in, is in the component's README (README.md:103-124).
| File | Shown as |
|---|---|
junit.xml | the pipeline's test report and the merge request widget |
annotations.json | links on the job page |
| one HTML page per failed task, and an index | the job's artifacts |
rerun.txt | the tasks a retry runs, through the job's cache |
A package or a source build installs only image-garden and image-garden.mk. For ubuntu-cloud-24.04.x86_64 the host supplies make, curl, xorriso, qemu-img, qemu-system-x86_64 and OVMF.
make install installs the image-garden script, image-garden.mk, the README and NEWS files and the man page, nothing else (Makefile:30-46); image-garden make runs the host's make on that file (image-garden:982-993).ubuntu-cloud-24.04.x86_64.run needs from scratch: the download (curl), the seed ISO (xorriso), the overlay and firmware copies (qemu-img), the provisioning boot (the emulator) and the UEFI firmware (OVMF). The order follows the chain of files in the target chain.image-garden.mk from source, not to run it (derived from Makefile:57-64).No tool is checked up front. Missing curl fails the download; program xorriso is required stops the seed ISO, program qemu-img is required the overlay. Finished downloads are kept.
XORRISO ?= $(or $(shell command -v xorriso),$(error program xorriso is required)) and CURL ?= $(or $(shell command -v curl),$(error curl is required)) --fail --silent --show-error --location (mk/000-garden.mk:20-21); QEMU_IMG ?= $(or $(shell command -v qemu-img),$(error program qemu-img is required)) (mk/010-qemu.mk:3). A variable set with ?= is expanded only where it is used, so each check runs when GNU make expands the first recipe that names it (derived from GNU make; confirmed by running the tree with each tool hidden from PATH: image-garden make list-systems succeeded each time).$(XORRISO) is used only by the seed ISO rule (mk/010-qemu.mk:268-278); $(QEMU_IMG) by the overlay and the unpack rules (rulegen.py:601-606, mk/010-qemu.mk:340-347); $(CURL) only by the URLProgram of Amazon Linux and Gentoo (data/gentoo.ini:9).curl itself, not $(CURL) (image-garden:110-119). Run without curl, it printed …/image-garden: 118: curl: not found and make stopped with Error 127 (run, /bin/sh being dash).image-garden.mk:LINE: *** program xorriso is required. Stop. (run).PATH, set XORRISO, CURL or QEMU_IMG (README.md:917-921). Setting CURL replaces the flags that follow the path too (derived from the ?= above).$(QEMU_IMG) too (mk/010-qemu-x86_64.mk:325-329), as does image-garden rebase, which reads QEMU_IMG from the environment (image-garden:970-980); one setting moves every qemu-img call.qemu-system-ARCH for each architecture you boot: x86_64, aarch64, riscv64, s390x, ppc64, loongarch64. A missing one warns, then the boot fails. A /dev/kvm you cannot write gets a warning too.
$(or $(shell command -v qemu-system-ARCH),$(warning program qemu-system-ARCH is required)qemu-system-ARCH): x86_64, aarch64, riscv64, s390x, ppc64, loongarch64. The warning appears when make expands a recipe that names the emulator (the provisioning boot and the .run script), twice per recipe (run on a host without qemu-system-x86_64); the recipe then runs the bare name, and the boot fails (derived).qemu-system-x86_64, -aarch64, -riscv64, -s390x, -ppc64 and -loongarch64, "or the emulators of the architectures you use" (README.md:122-126).kvm_check, run by image-garden make and allocate, prints a large WARNING when /dev/kvm exists but is not writable, then suggests sudo usermod -aG kvm $LOGNAME, or, with CI set, sudo chmod 666 /dev/kvm (image-garden:670-709, :985).qemu-system-misc, for example, carries loongarch64 (derived; see LoongArch).x86_64 UEFI systems need OVMF; without it every make warns please install x86_64 edk2 firmware - not in …. The +tpm systems also need swtpm and the Secure Boot OVMF pair.
/usr/share/OVMF/OVMF_CODE.fd, /usr/share/OVMF/OVMF_CODE_4M.fd, /usr/share/ovmf/x64/OVMF_CODE.4m.fd, /usr/share/qemu/ovmf-x86_64-4m-code.bin, and the matching variables (mk/010-qemu-x86_64.mk:260-270). Every UEFI architecture has its own lists; see UEFI firmware per system.efi-code.x86_64.img; with none, $(warning please install x86_64 edk2 firmware - not in …) (mk/010-qemu-x86_64.mk:318-322). Prerequisites are expanded when make reads the file, so image-garden make list-systems printed one warning per list for every UEFI architecture without firmware (run).OVMF_CODE_4M.secboot.fd and OVMF_VARS_4M.ms.fd; without one, the copy fails with "please install x86_64 edk2 firmware with Secure Boot and Microsoft keys (the ovmf package) - not in …" (mk/010-qemu-x86_64.mk:286-308).command -v $(SWTPM) first and stops with "swtpm, the TPM emulator, is required: install the swtpm package" (mk/050-ubuntu-core.mk:74-79, mk/010-qemu-x86_64.mk:119-120); their launcher checks again on every start.swtpm and the ovmf package" (README.md:717-718, README.md:122-126).Also used: flock, sha256sum, sha512sum, shuf, timeout, bash, and unxz for Ubuntu Core. Optional: spread, virtiofsd, and a pkgproxy named by PKGPROXY_URL.
FILE.lock with flock 9 (image-garden:374, :476, :583) and checks with sha512sum --check or sha256sum --check (image-garden:442, :544). The unpack and convert rules lock with flock too (mk/010-qemu.mk:321-332).allocate picks a port with shuf -i 5000-9999 -n 1 (image-garden:1100) and probes it with bash's /dev/tcp under timeout: "bash and timeout are essential packages" (image-garden:790-822)..img.xz, unpacked with unxz (mk/010-qemu.mk:340-344). That flock, shuf and timeout come with util-linux and coreutils, and unxz with xz, on most distributions is derived.PKGPROXY_URL" (README.md:103-105). image-garden does not start virtiofsd itself.PKGPROXY_URL must be http://host[:port]; make resolves the host to IPv4 when it prepares a system (mk/010-qemu.mk:24-29). The host name on the slide is the README's example.Next: installing from source, distribution packages, the distribution QEMU, firmware, the TPM systems and the architectures.
Read in the image-garden source at the pinned commit ("code"): mk/*.mk, rulegen.py, the image-garden script and the README. The order in which missing tools are reported and the messages were checked by running image-garden make and make -n from a source tree, with the tools hidden from PATH ("run"). Which distribution package holds which tool is "derived".
| Tool | Needed for | Override | When it is missing |
|---|---|---|---|
make | everything: image-garden make runs it | the shell's "not found" | |
curl | checksum lists and images; URLProgram systems | CURL (URLProgram only) | curl: not found from the download helper; curl is required for Amazon Linux and Gentoo |
xorriso | the cloud-init seed ISO | XORRISO | program xorriso is required |
qemu-img | the overlay, firmware copies, unpacked images, rebase | QEMU_IMG | program qemu-img is required |
qemu-system-ARCH | the provisioning boot and the .run script | QEMU_SYSTEM_X86_64 and siblings | warning program qemu-system-ARCH is required, then the boot fails |
| EDK2 firmware | systems with Boot=efi | QEMU_EDK2_CODE_ARCH, QEMU_EDK2_VARS_ARCH, GARDEN_ARCH_PREFIX | warning please install ARCH edk2 firmware - not in … on every make |
| Secure Boot OVMF pair | the four +tpm systems | QEMU_EDK2_SECBOOT_CODE_X86_64, …_VARS_X86_64 | please install x86_64 edk2 firmware with Secure Boot and Microsoft keys (the ovmf package) |
swtpm | the four +tpm systems | SWTPM | swtpm, the TPM emulator, is required: install the swtpm package |
unxz | Ubuntu Core .img.xz images | the shell's "not found" | |
flock, sha256sum, sha512sum | download locks and checks | the shell's "not found" | |
shuf, timeout, bash | allocate's port | "cannot probe TCP port … with bash and timeout" |
Sources: mk/000-garden.mk:20-21, mk/010-qemu.mk:3, mk/010-qemu-x86_64.mk:3-4, :260-329, mk/050-ubuntu-core.mk:74-79, image-garden:110-119, :790-822, README.md:913-921.
| Architecture | Emulator | Firmware |
|---|---|---|
| x86_64 | qemu-system-x86_64 | OVMF (EDK2) for efi systems; none for bios |
| aarch64 | qemu-system-aarch64 | AAVMF (EDK2); ten older systems use Fedora's build and Ubuntu 14.04 and 16.04 a 2022 build, which a native install downloads by checksum into the cache |
| riscv64 | qemu-system-riscv64 | EDK2 for RISC-V |
| loongarch64 | qemu-system-loongarch64 | EDK2 for LoongArch |
| s390x | qemu-system-s390x | none |
| ppc64 | qemu-system-ppc64 | none |
The search lists for every architecture are in UEFI firmware per system.
| Extra | What for | Where it comes from |
|---|---|---|
| spread | running spread tests against garden systems | a system package |
| virtiofsd | sharing a host directory with a guest | a system package |
| pkgproxy | caching images and guest packages | anywhere reachable; name it with PKGPROXY_URL |
write access to /dev/kvm | KVM instead of emulation | the kvm group on most distributions |
Arch Linux (AUR), Debian, Fedora and openSUSE package image-garden. The command and the make rules are the same; the tools around them come from your system.
Virtualization project) and Fedora (README.md:96-112).PKGPROXY_URL", virtiofsd as a system package and $XDG_CACHE_HOME for the cache (README.md:96-106).image-garden script on the same image-garden.mk (three ways in).The package: image-garden and image-garden.mk. Your system: QEMU, qemu-img, EDK2, swtpm and OVMF, spread. pkgproxy by PKGPROXY_URL; downloads in ~/.cache/image-garden.
make install installs, the image-garden script and image-garden.mk, with the README, NEWS files and man page (Makefile:29-46); the packages themselves were not inspected for this map.qemu-system-<arch> from PATH; a missing one is a warning, for example for x86_64 (mk/010-qemu-x86_64.mk:3-4); qemu-img is required (mk/010-qemu.mk:3)./usr/share/OVMF/…, then Arch Linux's and openSUSE's paths (mk/010-qemu-x86_64.mk:260-270); aarch64 looks in /usr/share/AAVMF and /usr/share/qemu. See firmware.PKGPROXY_URL gives guests a pkgproxy by address, and image downloads go through it too (mk/010-qemu.mk:24-29); a distribution QEMU has no guestfwd patch, so there is no socket mode (the distribution's QEMU).GARDEN_CACHE_DIR is $XDG_CACHE_HOME/image-garden, and XDG_CACHE_HOME defaults to ~/.cache (mk/000-garden.mk:9-12).Distribution packages, such as Debian's and Fedora's, may be older than the upstream release: the maintainer's statement. Features on this map may be newer than your package.
opencloudos-cloud-9 (the first loongarch64 system) and image downloads through pkgproxy are listed as new features of image-garden 0.8.0, the release this map builds on (NEWS:43-58).image-garden version, image-garden news [N] and image-garden make list-systems. Compare the list with the support matrix.
image-garden version (or --version) prints image-garden VERSION, the version written in at install time (image-garden:909-911).image-garden news [N] prints, from NEWS, then NEWS.snappy and NEWS.docker where installed, the newest section, or that and N more, each "Changes in" heading framed with *** (image-garden:912-942). Which NEWS files a package installs is up to the package; the tree's make install installs all three.image-garden make list-systems echoes every name in GARDEN_SYSTEMS, one per line (mk/000-garden.mk:85-87). Run for this map on a source install of v0.8.0: 160 lines, among them ubuntu-core-24+tpm.x86_64 and opencloudos-cloud-9.loongarch64.make: *** No rule to make target 'NAME.run'. Stop. means a typo or a system newer than your package. Check list-systems; for newer systems use the snap, the container or a source build.
LC_ALL=C image-garden make no-such-system.x86_64.run printed make: *** No rule to make target 'no-such-system.x86_64.run'. Stop. The message is GNU make's own; image-garden adds nothing to it (image-garden:982-993). With another locale, make prints it in that language.list-systems names what the installed version knows (mk/000-garden.mk:85-87).Next: what the host needs, the distribution's QEMU, a source build, the support matrix, image-garden make and the snap.
The package links are in the README of image-garden at the pinned commit ("code"). That distribution packages, such as Debian's and Fedora's, may be older than the upstream release is the maintainer's statement; check your distribution's version against the release notes before relying on a feature. The command output below was produced by running a source install of v0.8.0; the packages themselves were not inspected.
| Distribution | Package |
|---|---|
| Arch Linux | AUR: image-garden |
| Debian | packaged on salsa.debian.org |
| Fedora | image-garden in Fedora |
| openSUSE | Virtualization/image-garden on the Open Build Service |
image-garden version against the newest release: features such as the +tpm systems, loongarch64 and image downloads through pkgproxy need image-garden 0.8.0.image-garden news prints the release notes of the installed version.PKGPROXY_URL. See your own QEMU.| Command | Prints |
|---|---|
image-garden version | image-garden VERSION |
image-garden news | the newest "Changes in" section of each installed NEWS file |
image-garden news N | that section and N more |
image-garden make list-systems | every system the installed version knows, one per line |
$ image-garden make ubuntu-core-26+tpm.x86_64.run make: *** No rule to make target 'ubuntu-core-26+tpm.x86_64.run'. Stop.
The same message comes from a misspelt name. If list-systems does not list the system, the package is older than the release that added it: wait for the distribution, or use the snap, the container or a source build.
make runs command -v qemu-system-x86_64 and writes the result into the provisioning command and the .run script. The snap and the container bring their own patched QEMU.
QEMU_SYSTEM_X86_64 ?= $(or $(shell command -v qemu-system-x86_64),$(warning program qemu-system-x86_64 is required)qemu-system-x86_64) (mk/010-qemu-x86_64.mk:3-4); in the snap it names the snap's qemu-system-x86-64 app. The other architectures do the same in their own mk/010-qemu-ARCH.mk.qemu_cmd=("$(QEMU_SYSTEM_X86_64)") (mk/010-qemu-x86_64.mk:94), and the provisioning boot runs exec $(QEMU_SYSTEM_X86_64) through QEMU_SYSTEM_X86_64_EFI_CMDLINE (rulegen.py:593-606, mk/010-qemu-x86_64.mk:13-15). With no emulator on PATH, make -n showed qemu_cmd=("qemu-system-x86_64") (run with v0.8.0)./usr/bin/qemu-system-x86_64 on the slide is an example: it is wherever command -v finds the emulator.qemu-patches/guestfwd-unix-socket.patch (Dockerfile:29-32, snap/snapcraft.yaml:327-341).Without the guestfwd unix socket patch there is no socket bridge, and outside the snap none is set up. PKGPROXY_URL=http://host:port works with any QEMU, for guests and for image downloads.
unix: form of guestfwd, one unix socket connection per guest connection (qemu-patches/guestfwd-unix-socket.patch:6-20); the guestfwd patch has the rest.pkgproxy.sock in $SNAP_COMMON, or under it for pkgproxy=snap; a PKGPROXY_URL wins over any socket (mk/010-qemu.mk:20-44). Outside the snap SNAP_COMMON is unset unless you set it (derived).PKGPROXY_URL=http://host[:port], make resolves the host to IPv4 with getent ahostsv4 and the guest gets that address as pkgproxy; no guestfwd is added (mk/010-qemu.mk:24-30). "Outside the snap, as in image-garden's container, make PKGPROXY_URL=http://host:port ... does the same" (proxy/README.md:122-127).PKGPROXY_URL too, unless GARDEN_DL_PKGPROXY is set (image-garden:31-38).localhost and 127.0.0.1 mean the guest itself; use the host's network address or 10.0.2.2, see an address that points back.PKGPROXY_URL names" (proxy/README.md:7-12).A distribution QEMU has its release's features, emulators and firmware. The .run script asks -accel help on every start and uses kvm:tcg or tcg.
-machine q35 and -cpu max (mk/010-qemu-x86_64.mk:5-6), with virtio-blk, virtio-net-pci and virtio-rng-pci devices (mk/010-qemu-x86_64.mk:8-11, :23-25, mk/010-qemu.mk:45). The other machines are in architectures.-cpu max enables every CPU feature the QEMU release can offer is QEMU's documented meaning of the model (derived)..run script computes default_qemu_accel_machine_prop by running the emulator with -accel help and choosing kvm:tcg when kvm is listed, tcg otherwise; QEMU_ACCEL_MACHINE_PROP overrides it (mk/010-qemu-x86_64.mk:63, :72).QEMU_SYSTEM_X86_64=… QEMU_IMG=… GARDEN_X86_64_PREFIX=… image-garden make SYSTEM.run. An existing .run keeps its QEMU path until you delete it.
QEMU_SYSTEM_X86_64, QEMU_SYSTEM_AARCH64, QEMU_SYSTEM_RISCV64, QEMU_SYSTEM_S390X, QEMU_SYSTEM_PPC64, QEMU_SYSTEM_LOONGARCH64, QEMU_IMG, XORRISO, CURL, SWTPM (README.md:913-921). They are set with ?= (mk/010-qemu-x86_64.mk:3-4, mk/010-qemu.mk:3), so the environment or image-garden make VAR=… wins.GARDEN_X86_64_PREFIX appends PREFIX/share/qemu/edk2-x86_64-code.fd and edk2-i386-vars.fd to the end of the x86_64 lists (mk/010-qemu-x86_64.mk:277-280); a distribution's OVMF earlier in the list still wins. aarch64, riscv64 and loongarch64 have their own prefix variables (UEFI firmware per system)./usr/local and sets the prefixes there (Dockerfile:98-102); its emulators are found through PATH (derived: /usr/local/bin comes first in the image's default PATH)..run rule depends on $(MAKEFILE_LIST) and, order-only, on the image and firmware (rulegen.py:593-599); a changed variable does not make it out of date (derived from GNU make). Deleting the .run makes only the script again; the prepared .qcow2 stays.$(QEMU_IMG) as well (mk/010-qemu-x86_64.mk:325-329), and so does image-garden rebase when QEMU_IMG is in the environment (image-garden:970-980)./opt/qemu on the slide is an example prefix.grep qemu_cmd= SYSTEM.run shows the path, --version the release, and grep -q slirp_add_unix on the binary whether it has the patch.
qemu_cmd=("PATH-TO-EMULATOR") (mk/010-qemu-x86_64.mk:94).grep -q slirp_add_unix "$qemu", and without it SKIP: $mode needs QEMU patched with qemu-patches/guestfwd-unix-socket.patch (tests/smoke-pkgproxy.sh:84-90).slirp_add_unix only when the patch calls it, is derived. The snap's QEMU is patched (snap/snapcraft.yaml:327-341).--version output line is QEMU's own (derived, not run).Next: the guestfwd patch, how a guest reaches pkgproxy, host tools, the container, the snap and the architectures.
Read in the image-garden source at the pinned commit ("code"): mk/010-qemu*.mk, rulegen.py, Dockerfile, snap/snapcraft.yaml, tests/smoke-pkgproxy.sh and the README. What make -n writes into a .run script with and without an emulator on PATH was checked by running v0.8.0 from a source tree ("run"). What a distribution packages, and QEMU's own behaviour, are "derived".
| Install | Emulator | Patched | Firmware |
|---|---|---|---|
| Distribution package or source | command -v qemu-system-ARCH when make writes the rules | no | the distribution's packages |
| Container | /usr/local/bin, built in the image | yes | built with QEMU, plus Ubuntu's ovmf |
| Snap | the image-garden.qemu-system-* apps, from the QEMU components | yes | in the QEMU components |
| Variable | Default outside the snap | What it changes |
|---|---|---|
QEMU_SYSTEM_X86_64 (and _AARCH64, _RISCV64, _S390X, _PPC64, _LOONGARCH64) | the emulator on PATH | the provisioning boot and the .run script |
QEMU_IMG | qemu-img on PATH | overlays, unpacked images and firmware copies; rebase reads it from the environment |
GARDEN_X86_64_PREFIX (and _AARCH64, _RISCV64, _LOONGARCH64) | unset | appends PREFIX/share/qemu/edk2-* to the firmware lists |
QEMU_ACCEL_MACHINE_PROP | ,accel=kvm:tcg or ,accel=tcg, asked on every start | the accelerator, per run |
grep qemu_cmd= ubuntu-cloud-24.04.x86_64.run /usr/bin/qemu-system-x86_64 --version grep -q slirp_add_unix /usr/bin/qemu-system-x86_64 && echo patched
The last line is the check image-garden's smoke test makes before it runs the socket modes (tests/smoke-pkgproxy.sh:84-90).
make && sudo make install in a checkout of the tree. Nothing is compiled: the result is a shell script and image-garden.mk.
make && sudo make install" (README.md:114-120).make builds image-garden.mk (all:: image-garden.mk); make install installs it with the script (Makefile:20-50). Nothing in the tree is compiled; image-garden is a /bin/sh script (image-garden:1).curl, the six emulators qemu-system-x86_64, -aarch64, -riscv64, -s390x, -ppc64 and -loongarch64 (or those of the architectures you use), qemu-img and xorriso, and for the Ubuntu Core systems with a TPM swtpm and the Secure Boot firmware (README.md:122-126).make, make install and the script on a git archive of the pinned commit.make runs rulegen.py once per data/*.ini, writes the systems list, and joins it, mk/*.mk and data/050-*.gen.mk into image-garden.mk.
data/050-%.gen.mk: rulegen.py data/%.ini runs ./rulegen.py data/NAME.ini >data/050-NAME.gen.mk; data/000-systems.mk is written by rulegen.py --systems-meta over every .ini (Makefile:57-64).image-garden.mk is cat data/000-systems.mk, the sorted mk/*.mk and the sorted data/050-*.gen.mk; touch --reference then gives it the time of its newest input (Makefile:48-50).$(MAKEFILE_LIST), so a time of the build would make every system's .url look out of date after any rebuild; see how image-garden.mk is put together.rulegen.py runs with Python 3; no QEMU tool is called while building image-garden.mk (run for this map on a host with QEMU; derived for one without).image-garden.mk, data/*.gen.mk and data/000-systems.mk are build output; make clean removes them (Makefile:23-27).make turns the tree's list of systems into rules and joins them with the hand-written ones into image-garden.mk. It needs Python, not QEMU.
make with no target builds image-garden.mk (Makefile:20-21). The list of systems is the tree's data/*.ini; the build writes one file of generated rules per data file and a list of every system's metadata, and concatenates that list, the hand-written mk/*.mk and the generated rules, each sorted, into image-garden.mk (Makefile:48-64).touch --reference gives image-garden.mk the time of its newest input (Makefile:48-50). Derived: rules in image-garden.mk compare a system's files with $(MAKEFILE_LIST), so a time of the build would make every system's .url look out of date after any rebuild.image-garden.mk (run for this map on a host with QEMU; derived for one without).make clean removes image-garden.mk and the intermediate files (Makefile:23-27).prefix ?= /usr/local: bin/image-garden, include/image-garden.mk, share/doc/image-garden/, share/man/man1/image-garden.1. sed fills in @PREFIX@, @INCLUDEDIR@, @DOCDIR@ and @VERSION@.
prefix ?= /usr/local, bindir, includedir = $(prefix)/include, datarootdir = $(prefix)/share, man1dir = $(datarootdir)/man/man1, and DESTDIR ?= (Makefile:3-14).install copies image-garden to $(bindir) and runs sed -i -e 's,@PREFIX@,$(prefix),' -e 's,@INCLUDEDIR@,$(includedir),' -e 's,@DOCDIR@,$(datarootdir)/doc/image-garden,' -e 's,@VERSION@,$(VERSION),' on it; image-garden.mk to $(includedir); README.md, NEWS, NEWS.snappy, NEWS.docker and their .license files to $(datarootdir)/doc/image-garden; image-garden.1 to $(man1dir) (Makefile:29-46).GARDEN_PREFIX=PREFIX, GARDEN_INCLUDE=INCLUDEDIR and GARDEN_DOC=DATAROOTDIR/doc/image-garden, so an includedir or datarootdir set apart from the prefix is followed (image-garden:10-12), and image-garden make runs make -f "$GARDEN_INCLUDE"/image-garden.mk (image-garden:987-993).make install DESTDIR=… prefix=/usr staged usr/bin/image-garden (with GARDEN_PREFIX=/usr), usr/include/image-garden.mk, usr/share/doc/image-garden/ with seven files and usr/share/man/man1/image-garden.1, and the staged script printed image-garden 0.8.0. With includedir=P/inc the script had GARDEN_INCLUDE=P/inc and found its makefile there (run at the pinned commit).image-garden news from a source install prints the main, the snap and the container notes (run).Uninstalled, the script finds image-garden.mk and NEWS next to its real path. image-garden version prints image-garden @VERSION@.
GARDEN_PREFIX is still the placeholder, the script sets GARDEN_ITSELF=$(readlink -f "$0") and uses its directory as GARDEN_PREFIX, GARDEN_INCLUDE and GARDEN_DOC: "This hacks supports both installed and uninstalled version equally" (image-garden:13-19).image-garden version prints image-garden @VERSION@ from an uninstalled tree; news reads NEWS next to the script (image-garden:909-917). Both run for this map.image-garden make list-systems, run from another directory with the script of the tree, listed the systems; make warned about EDK2 firmware missing on that host, as any install does.make must have built image-garden.mk first: the script runs make -f on it (image-garden:987-993).~/bin and ~/project on the slide are examples.make check: check-sh (shellcheck), check-py (mypy --strict), check-rulegen, check-dl-pkgproxy, check-allocate, check-rebase, check-dl-unpack-lock, check-pkgproxy-guest-shell.
check depends on check-sh check-py check-rulegen check-dl-pkgproxy check-allocate check-rebase check-dl-unpack-lock check-pkgproxy-guest-shell (Makefile:66-67).check-sh runs shellcheck over FILES_SH: the script, spread-chooser, the snap's hooks, qemu-stubs/, docker-stubs/docker and the test scripts; check-py runs mypy --strict over rulegen.py and three test helpers (Makefile:69-97); the list also holds qemu-stubs/virtiofsd and tests/ci/run-systems.sh. A missing checker is $(error program shellcheck is required) or … mypy is required (Makefile:90, Makefile:94).tests/check-rulegen.sh (valid and invalid image definitions, and no Python traceback for a data mistake), check-dl-pkgproxy.sh (downloads through a stand-in pkgproxy, tests/dl-pkgproxy-server.py), check-allocate.sh (ports and SSH, with tests/fake-sshd.py), check-rebase.sh (rebase of a prepared image whose download moved to another GARDEN_DL_DIR, named with and without .qcow2; it runs qemu-img, tests/check-rebase.sh:1-39), check-dl-unpack-lock.sh (concurrent unpacking of one download, "No network, no KVM"), check-pkgproxy-guest-shell.sh (the guests' pkgproxy setup under dash and busybox sh) (Makefile:99-115).build-garden stage installs qemu-utils among its tools and runs make check before make install (Dockerfile:58-71).make fmt formats with shfmt and black (Makefile:117-126).make: INCLUDEDIR/image-garden.mk: No such file or directory means the script cannot find its makefile where make install put it. Install both files together, with the same prefix and includedir.
@INCLUDEDIR@, which make install replaces with $(includedir), the directory it copies image-garden.mk to; @DOCDIR@ becomes $(datarootdir)/doc/image-garden, where the release notes go (image-garden:10-12, Makefile:12, Makefile:29-40). An uninstalled script looks next to itself instead (image-garden:13-19).make install prefix=P includedir=P/inc the script had GARDEN_INCLUDE=P/inc, and image-garden make list-systems listed the systems. With P/inc/image-garden.mk removed, and LC_ALL=C, it printed make: P/inc/image-garden.mk: No such file or directory and make: *** No rule to make target 'P/inc/image-garden.mk'. Stop. The slide uses /opt/ig for P.image-garden make runs make -f "$GARDEN_INCLUDE"/image-garden.mk (image-garden:987-993).Next: what the host needs, distribution packages, the container image and image-garden make.
Next: what the host needs, how image-garden.mk is assembled, rulegen, distribution packages, the container image and image-garden make.
Read in the Makefile, image-garden and README of image-garden at the pinned commit ("code"), and checked by running make, make install (with DESTDIR, prefix and includedir) and the uninstalled script on a git archive of that commit ("run").
| Target | What it does |
|---|---|
make (all) | builds image-garden.mk from data/*.ini and mk/*.mk |
make install | installs the script, image-garden.mk, the docs and the man page |
make clean | removes image-garden.mk, data/050-*.gen.mk and data/000-systems.mk |
make check | shellcheck, mypy --strict and six tests (one needs qemu-img) |
make fmt | shfmt and black over the scripts |
make dist | image-garden-VERSION.tar.gz of the sources |
make docker-test-smoke | builds the container image and runs three smoke tests |
| Variable | Default | Holds |
|---|---|---|
prefix | /usr/local | everything below |
bindir | $(prefix)/bin | image-garden |
includedir | $(prefix)/include | image-garden.mk; written into the script, which looks there |
datarootdir | $(prefix)/share | doc/image-garden/: README.md, NEWS, NEWS.snappy, NEWS.docker and their licences; written into the script for image-garden news |
man1dir | $(datarootdir)/man/man1 | image-garden.1 |
DESTDIR | empty | a staging root, for packaging |
make && sudo make install # /usr/local make install DESTDIR=$PWD/stage prefix=/usr # stage a package's files ./image-garden version # uninstalled: image-garden @VERSION@ make check # needs shellcheck and mypy
| Message | Cause |
|---|---|
program shellcheck is required | make check without shellcheck (or mypy) |
make: INCLUDEDIR/image-garden.mk: No such file or directory | the script's makefile is not where make install put it |
image-garden @VERSION@ | the script runs uninstalled, from the tree |
GitLab.com's hosted runners have no /dev/kvm: guests would be emulated, many times slower. Run image-garden jobs on runners of your own.
/dev/kvm to run machines at full speed; without it QEMU emulates the CPU (TCG), many times slower. GitLab.com's hosted runners do not give jobs /dev/kvm (README.md:778-785).image-garden make warns when /dev/kvm exists but is not writable (image-garden:670-671).In the runner's config.toml, [runners.docker] takes devices = ["/dev/kvm"]. Tag the runner, for example kvm, and the jobs with the same tag.
devices = ["/dev/kvm"] in the docker executor's config.toml, picked with tags (README.md:782-785).devices belongs to the [runners.docker] section of a runner that uses the docker executor; the job itself needs no option. The tag name kvm is this map's example; image-garden's own pipeline uses kvm and kvm-large (.gitlab-ci.yml:49, .gitlab-ci.yml:627-630).The published image covers x86_64 and aarch64 hosts. Tag jobs with the host architecture too, such as [kvm, x86_64]: KVM helps only guests of the host's own architecture.
docker-arch builds the image natively on an x86_64 and an aarch64 runner; docker-manifest joins them as the release tag and latest (.gitlab-ci.yml:1231-1278)..run script asks for kvm:tcg when KVM is there and falls back to TCG (010-qemu-x86_64.mk:17).tags: [linux, x86_64, kvm] (.gitlab-ci.yml:623-633) and tags: [aarch64, kvm, linux] (.gitlab-ci.yml:649-659).qemu-emulated, "on slots of their own, never holding up short jobs", where each image boots only once (GARDEN_TEST_BOOT_ONLY) and a failure does not fail the pipeline (.gitlab-ci.yml:663-678).image: registry.gitlab.com/zygoon/image-garden:v0.8.0, tags: [kvm, x86_64], QEMU_MEM_OPTION and QEMU_SMP_OPTION in variables, then image-garden make.
QEMU_SMP_OPTION: -smp 2, QEMU_MEM_OPTION: -m 1024 variables those jobs set (.gitlab-ci.yml:568-569).ubuntu:rolling rather than use the container (.gitlab-ci.yml:275-316), then run tests/ci/run-systems.sh for a cluster of systems (.gitlab-ci.yml:542-593); for each system it runs image-garden make "$system.$arch.run" and, in spread-demo, make spread-"$system" (tests/ci/run-systems.sh:58-113).No CI cache of images: set PKGPROXY_URL (or GARDEN_DL_PKGPROXY) in the runner's config.toml environment, and every job downloads through one pkgproxy.
GARDEN_DL_PKGPROXY in its environment (config.toml), and image-garden downloads each image, and the spread binary, through it, by checksum (.gitlab-ci.yml:550-556).PKGPROXY_URL does the same for image downloads and also gives the guests a pkgproxy; one pkgproxy downloads each image once for every machine and CI job, and an unreachable one is skipped (README.md:234-255).10.0.0.5, is an example. Derived: in GitLab Runner's config.toml, environment under [[runners]] sets variables for every job of that runner. The address must be reachable from the job container's network.Next: spread-gitlab-ci, the craft components, why pkgproxy, and the container on GitLab against the snap on GitHub.
Read in the README and .gitlab-ci.yml of image-garden at the pinned commit ("code"). The runner configuration and the job below are examples, not run for this map ("derived").
[[runners]] name = "garden-x86_64" executor = "docker" environment = ["PKGPROXY_URL=http://10.0.0.5:3142"] [runners.docker] devices = ["/dev/kvm"]
Register it with the tags kvm and its architecture, x86_64 or aarch64.
garden-tests: image: registry.gitlab.com/zygoon/image-garden:v0.8.0 tags: [kvm, x86_64] variables: QEMU_MEM_OPTION: -m 1024 QEMU_SMP_OPTION: -smp 2 script: - image-garden make ubuntu-cloud-24.04.x86_64.run
| Choice | Why |
|---|---|
| runners of your own | hosted GitLab.com runners give no /dev/kvm |
devices = ["/dev/kvm"] | the job container gets the device without asking |
| a tag per host architecture | KVM helps only guests of the host's architecture |
a release tag of the image, not latest | the job stays the same until you change it |
PKGPROXY_URL in the runner's environment | images and packages are downloaded once, with no CI cache |
| no GitLab cache of images | hundreds of MB per job cost more to move than to fetch through pkgproxy |
The image is built by the Dockerfile in image-garden's tree, in three stages, and published with every release.
Dockerfile at the top of the tree, in three stages: build-qemu, build-garden and the final stage, each FROM ubuntu:latest (Dockerfile:5, Dockerfile:58, Dockerfile:73).docker-arch) and publishes it for a tag only (docker-manifest) (.gitlab-ci.yml:1231-1278).snap/snapcraft.yaml, with the same QEMU patch (px-patch).build-qemu compiles QEMU, build-garden runs make, make check and make install, and the final stage copies /usr/local from both onto a clean Ubuntu.
build-qemu installs bison, flex, g++, meson, ninja and the development libraries QEMU needs, then builds and installs QEMU with --prefix=/usr/local (Dockerfile:5-54).build-garden installs curl, make, mypy, shfmt, python3, qemu-utils (for the rebase test), shellcheck and xz-utils, adds the tree, and runs make --warn-undefined-variables && make check && make install --warn-undefined-variables (Dockerfile:58-71). A failing command fails the build (derived from Docker's RUN).ca-certificates, curl, git, git-restore-mtime, libcurl3t64-gnutls, libfdt1, libslirp0, make, ovmf, swtpm, xorriso and xz-utils, then copies /usr/local from build-qemu and from build-garden (Dockerfile:73-104).make check runs are listed in a source build.The tarball is pinned by its sha256, patched with guestfwd-unix-socket.patch, configured with --without-default-features plus a short list of features, for six targets, and stripped.
ADD --checksum=sha256:… https://download.qemu.org/qemu-11.1.3.tar.xz /src/: Docker verifies the checksum of the download (Dockerfile:6).qemu-patches/guestfwd-unix-socket.patch is copied in and applied with patch -p1 (Dockerfile:29-32); the comment says it is the same patch as the snap's QEMU.configure --without-default-features with --enable-attr --enable-kvm --enable-pie --enable-slirp --enable-strip --enable-system --enable-tcg --enable-tools --enable-tpm --enable-vhost-crypto --enable-vhost-kernel --enable-vhost-net --enable-vhost-user --enable-virtfs, and QEMU_TARGET_LIST=x86_64-softmmu,aarch64-softmmu,riscv64-softmmu,s390x-softmmu,ppc64-softmmu,loongarch64-softmmu (Dockerfile:33-54).--without-default-features, display back ends such as GTK, SDL and VNC are not built. image-garden's .run scripts use -nographic by default (mk/010-qemu.mk:13), so a QEMU_DISPLAY_OPTION that asks for a window does not work in the container.GARDEN_CACHE_DIR=/var/cache/image-garden (a volume), GARDEN_*_PREFIX=/usr/local for the EDK2 firmware, ovmf and swtpm, and no NEWS.snappy.
ENV GARDEN_CACHE_DIR=/var/cache/image-garden and VOLUME /var/cache/image-garden (Dockerfile:96-97); mount a directory there to keep downloads, as running the container shows.GARDEN_X86_64_PREFIX, GARDEN_AARCH64_PREFIX, GARDEN_RISCV64_PREFIX and GARDEN_LOONGARCH64_PREFIX are /usr/local (Dockerfile:99-102), one for each architecture whose firmware list reads a prefix. The x86_64 makefile, for example, appends $(GARDEN_X86_64_PREFIX)/share/qemu/edk2-x86_64-code.fd to its search list (mk/010-qemu-x86_64.mk:277-280); see firmware for the order. s390x and ppc64 take no firmware file, and the image sets no prefix for them.ovmf and swtpm come from Ubuntu (Dockerfile:78-91), for the Ubuntu Core systems with a TPM (NEWS.docker:5-6).rm -f /usr/local/share/doc/image-garden/NEWS.snappy* (Dockerfile:104); image-garden news prints NEWS, NEWS.snappy and NEWS.docker, skipping those that are missing (image-garden:912-942).git config --system alias.whatchanged 'log --raw --no-merges': git restore-mtime runs git whatchanged, which the image's git refuses to run (Dockerfile:92-95).ENV values are defaults; docker run -e NAME=VALUE replaces them for that container.docker-arch builds per architecture in every pipeline; docker-manifest joins them, for a tag only, as the tag and latest. The base is ubuntu:latest at build time.
docker-arch runs on runners tagged [$ARCH, docker] for x86_64 and aarch64, builds with docker build --pull and pushes $CI_REGISTRY_IMAGE/ci:pipeline-$CI_PIPELINE_ID-$ARCH; "Every pipeline builds them, so a merge request shows that the image builds" (.gitlab-ci.yml:1231-1255).docker-manifest joins the two with docker buildx imagetools create as $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG and :latest, for a tag only and never in a schedule (.gitlab-ci.yml:1257-1278). The image is registry.gitlab.com/zygoon/image-garden.FROM ubuntu:latest; the README: it "resolves to the current Ubuntu LTS release" (README.md:346-349). --pull fetches the newest base at build time. The image carries LABEL version with the release (Dockerfile:74).ubuntu:latest. latest moves with every release.docker build -t image-garden:latest . in the tree, or make docker-test-smoke to build and try it. To extend it, start FROM registry.gitlab.com/zygoon/image-garden:TAG, as spread-gitlab-ci does.
docker-test-smoke runs docker build -t image-garden:latest ., then three docker runs with /dev/kvm when the host has it and the cache volume: ldd on qemu-img and the six qemu-system-*, image-garden news, and image-garden make -C /tmp ubuntu-cloud-24.04.$(uname -m).run; docker-test-all makes all -k (Makefile:137-166).FROM registry.gitlab.com/zygoon/image-garden:v0.7.0 AS base and adds spread, spread-plus and spread-gitlab-report with ADD --checksum, per architecture (spread-gitlab-ci Dockerfile:18-34). It builds on an older image-garden than the one this map describes (see spread-gitlab-ci).Next: running the container, the container in CI, pkgproxy from a container, the guestfwd patch, firmware, and spread-gitlab-ci.
Read in the Dockerfile, Makefile, NEWS.docker, README and .gitlab-ci.yml of image-garden at the pinned commit ("code"). The image was not built for this map; what follows from Docker's multi-stage builds is marked "derived" in the slides' details.
| Stage | Starts from | Installs | Runs | Leaves for the image |
|---|---|---|---|---|
build-qemu | ubuntu:latest | bison, bzip2, device-tree-compiler, flex, g++, gnutls-dev, libcurl4-gnutls-dev, libfdt-dev, libglib2.0-dev, libncurses-dev, libslirp-dev, make, meson, ninja-build, patch, python3-pip, uuid-dev, xz-utils, zlib1g-dev | the checked tarball, the guestfwd patch, configure, make, make install | QEMU in /usr/local |
build-garden | ubuntu:latest | curl, make, mypy, shfmt, python3, qemu-utils, shellcheck, xz-utils | make, make check, make install | image-garden in /usr/local |
| final | ubuntu:latest | ca-certificates, curl, git, git-restore-mtime, libcurl3t64-gnutls, libfdt1, libslirp0, make, ovmf, swtpm, xorriso, xz-utils | the git alias, rm of NEWS.snappy* | the image |
configure --without-default-features \ --enable-attr --enable-kvm --enable-pie --enable-slirp \ --enable-strip --enable-system --enable-tcg --enable-tools \ --enable-tpm --enable-vhost-crypto --enable-vhost-kernel \ --enable-vhost-net --enable-vhost-user --enable-virtfs \ --prefix=/usr/local \ --target-list=x86_64-softmmu,aarch64-softmmu,riscv64-softmmu,s390x-softmmu,ppc64-softmmu,loongarch64-softmmu
| Variable | Value | Read by |
|---|---|---|
GARDEN_CACHE_DIR | /var/cache/image-garden (a volume) | image-garden and its makefile |
GARDEN_X86_64_PREFIX | /usr/local | mk/010-qemu-x86_64.mk |
GARDEN_AARCH64_PREFIX | /usr/local | mk/010-qemu-aarch64.mk |
GARDEN_RISCV64_PREFIX | /usr/local | mk/010-qemu-riscv64.mk |
GARDEN_LOONGARCH64_PREFIX | /usr/local | mk/010-qemu-loongarch64.mk |
No ENTRYPOINT or CMD is set.
# in a checkout of the image-garden tree docker build -t image-garden:latest . # or: podman build ... make docker-test-smoke # build, then three test runs
| Job | When | Result |
|---|---|---|
docker-arch | every pipeline, on an x86_64 and an aarch64 runner | ci:pipeline-ID-ARCH in the project's registry |
docker-manifest | a tag, never a schedule | registry.gitlab.com/zygoon/image-garden:TAG and :latest |
No pkgproxy in the image and no socket mode: -e PKGPROXY_URL=http://HOST:PORT is read by image-garden for image downloads and by make for the guests it prepares.
PKGPROXY_URL" for pkgproxy (README.md:104).$(PKGPROXY_SOCKET_DIR)/pkgproxy.sock exists, and PKGPROXY_SOCKET_DIR is built from SNAP_COMMON (mk/010-qemu.mk:20-44). In the container SNAP_COMMON is unset, so make tests /pkgproxy.sock, which the image does not have (derived). The image's QEMU carries the guestfwd patch all the same (Dockerfile:29-32); see what you lose without it.PKGPROXY_URL for image downloads unless GARDEN_DL_PKGPROXY is set (image-garden:31-38); make writes the guest's /etc/hosts entry, the apt and snap setup and GOPROXY into its user-data (mk/010-qemu.mk:127-180).pkgproxy.lan on the slide is an example name. Outside the snap, make PKGPROXY_URL=… and PKGPROXY_URL in the environment work the same (proxy/README.md:121-127).image-garden connects from the container, the guest from behind QEMU's user network inside it. 127.0.0.1 and 10.0.2.2 stay inside the container; use the pkgproxy machine's network address.
getent ahostsv4 where make runs, here inside the container, and writes the address as pkgproxy in the guest's /etc/hosts; a host that does not resolve gives cannot use pkgproxy at "…": want http://host[:port] with a host that resolves to IPv4; guests get no pkgproxy (mk/010-qemu.mk:24-29).image-garden make ubuntu-cloud-24.04.x86_64.user-data outside the snap: with PKGPROXY_URL=http://localhost:3142 the user-data adds 127.0.0.1 pkgproxy to /etc/hosts; with a name that does not resolve it has no pkgproxy lines and make prints the warning above.10.0.2.2 is the host's loopback as a guest of QEMU's user network sees it (tests/smoke-pkgproxy.sh:229-233). Derived: when QEMU runs in a container, that host is the container, so 10.0.2.2 reaches only what listens on the container's loopback, and image-garden in the container cannot use that address at all.host-gateway (ext-craft-pkgproxy).GARDEN_DL_PKGPROXY overrides PKGPROXY_URL for images only: another URL, empty for direct downloads, or unix:/path/pkgproxy.sock for a mounted socket. Guests follow PKGPROXY_URL.
GARDEN_DL_PKGPROXY is set, even empty, image-garden does not take PKGPROXY_URL for downloads (image-garden:31-38); empty turns downloads through pkgproxy off (README.md:246-248).unix:PATH is reached with curl --unix-socket PATH and the URL http://pkgproxy/… (image-garden:121-136, image-garden:297-298); the README names the form (README.md:273-278). A socket is never remembered as unreachable: connecting to it fails at once (image-garden:149).PKGPROXY_URL outside the snap (mk/010-qemu.mk:20-44).-v; the path /run/pkgproxy.sock and HOST-SOCKET on the slide are placeholders. The user in the container needs permission to connect to it.A and B stand for the addresses of two pkgproxies.An unreachable pkgproxy is remembered for five minutes in /run/image-garden, inside the container, and forgotten when it exits. Each new container tries once, with a 10 second connect timeout.
--connect-timeout 10; on failure "Cannot download through pkgproxy, downloading URL directly" (image-garden:287-307).$XDG_RUNTIME_DIR/image-garden/pkgproxy-unreachable.HASH and says "Not asking pkgproxy at … again for 5 minutes"; for 300 seconds each download says "Skipping pkgproxy at …, unreachable recently, downloading … directly" (image-garden:138-193).XDG_RUNTIME_DIR the directory is /run, "as for root in a container"; where /run/image-garden cannot be made, nothing is remembered (image-garden:61-64, image-garden:138-143, README.md:254-258)./run in a container is part of the container, so the note goes with it; a new container starts without it.Next: how a guest reaches pkgproxy, image downloads, an unreachable pkgproxy, changing the proxy, the runner's environment, and the craft components.
Read in image-garden, mk/010-qemu.mk, the README and proxy/README.md of image-garden v0.8.0 ("code"). The guest addresses were checked by running image-garden make ubuntu-cloud-24.04.x86_64.user-data outside the snap. The container commands below were not run for this map; what follows from container networking is "derived".
| Variable | Read by | Effect in the container |
|---|---|---|
PKGPROXY_URL | image-garden and make | image downloads, unless GARDEN_DL_PKGPROXY is set; guests' apt, snap and Go setup |
GARDEN_DL_PKGPROXY | image-garden | image downloads only: a URL, unix:PATH, or empty for none |
# one pkgproxy for everything docker run --rm -it --device /dev/kvm \ -v $HOME/.cache/image-garden:/var/cache/image-garden \ -e PKGPROXY_URL=http://pkgproxy.lan:3142 \ registry.gitlab.com/zygoon/image-garden:TAG \ image-garden make ubuntu-cloud-24.04.x86_64.run
# guests through the URL, images through a mounted socket -v /path/to/pkgproxy.sock:/run/pkgproxy.sock \ -e PKGPROXY_URL=http://pkgproxy.lan:3142 \ -e GARDEN_DL_PKGPROXY=unix:/run/pkgproxy.sock
# guests through the URL, images straight from their origin -e PKGPROXY_URL=http://pkgproxy.lan:3142 \ -e GARDEN_DL_PKGPROXY=
| Address in PKGPROXY_URL | From image-garden in the container | From the guest |
|---|---|---|
127.0.0.1 or localhost | the container | the guest itself |
10.0.2.2 | not reachable | the container's loopback |
| the pkgproxy machine's LAN address or name | the pkgproxy | the pkgproxy |
The container is image-garden with all its tools, for x86_64 and aarch64 hosts. Run it with docker or podman and use the usual commands inside.
FROM ubuntu:latest with image-garden, QEMU and the tools it runs (Dockerfile:73-104).v0.8.0) and latest, at registry.gitlab.com/zygoon/image-garden (.gitlab-ci.yml:1231-1278). Docker and podman pull the variant of the host's architecture.QEMU for six architectures with the guestfwd patch, qemu-img, image-garden, make, curl, xorriso, xz, git, swtpm and OVMF. No spread, no pkgproxy, no entrypoint.
qemu-patches/guestfwd-unix-socket.patch applied, for x86_64, aarch64, riscv64, s390x, ppc64 and loongarch64 system emulation, with tools (qemu-img) (Dockerfile:5-54)./usr/local (Dockerfile:58-71, Dockerfile:103).ca-certificates, curl, git, git-restore-mtime, libcurl3t64-gnutls, libfdt1, libslirp0, make, ovmf, swtpm, xorriso, xz-utils (Dockerfile:78-91).GARDEN_X86_64_PREFIX, GARDEN_AARCH64_PREFIX, GARDEN_RISCV64_PREFIX and GARDEN_LOONGARCH64_PREFIX, all /usr/local, point image-garden at the EDK2 firmware built with QEMU (Dockerfile:99-102); s390x and ppc64 need no firmware file.ENTRYPOINT or CMD, and installs no spread and no pkgproxy.--device /dev/kvm for speed, --volume ~/.cache/image-garden:/var/cache/image-garden to keep downloads, then image-garden make SYSTEM.run.
GARDEN_CACHE_DIR=/var/cache/image-garden and declares it a VOLUME (Dockerfile:96-97).--device /dev/kvm and --volume $HOME/.cache/image-garden:/var/cache/image-garden, for docker and podman alike (README.md:758-776). Without /dev/kvm, QEMU emulates the CPU (TCG), many times slower (README.md:780-781).image-garden make -C /tmp ubuntu-cloud-24.04.$(uname -m).run as the command (Makefile:137-157).image-garden make ubuntu-cloud-24.04.x86_64.run (README.md:768, README.md:775), as the smoke test does. The image has no entrypoint, so the command has to be image-garden make: plain make would run GNU make without image-garden's makefile (derived from the Dockerfile).Mount the project with -v "$PWD:/src" -w /src. Files are made there, or in .image-garden/, and .image-garden.mk is read as on the host.
image-garden make runs make in .image-garden/ when the project has that directory, and in the current directory otherwise (image-garden:982-993)..image-garden.mk is included from GARDEN_PROJECT_DIR, the directory image-garden was started in (999-local.mk:4-5).-v "$PWD:/src" -w /src is the usual docker way to make the project the working directory; image-garden's notes use it to run a CI component's image on a checkout (proxy/README.md:277-279)..qcow2 is an overlay whose backing file is the download in the cache directory: with another cache, see rebase.allocate forwards 127.0.0.1:PORT inside the container. Run ssh or spread in the same container, then image-garden discard.
127.0.0.1:PORT to the guest's port 22 (image-garden:1107); it starts the .run script with -snapshot and -daemonize (image-garden:1153-1163).127.0.0.1 is the container's own loopback, so the forwarded port is reachable from inside it only, unless the port is published, which allocate's random port makes awkward.ssh or spread, in the same job container (findings/research-integrations.md).-e PKGPROXY_URL=http://pkgproxy.example.lan:3142 sends image downloads and guest packages through a pkgproxy that the container can reach.
PKGPROXY_URL set, make takes the host and port from it and resolves the host to an IPv4 address when it makes a system's files; a host that does not resolve leaves guests without pkgproxy, with a warning (010-qemu.mk:24-30). The guest then knows that address as pkgproxy.GARDEN_DL_PKGPROXY says otherwise (image-garden:31-38).10.0.2.100, are set up by the snap; outside it, PKGPROXY_URL is the way (proxy/README.md:7-12, proxy/README.md:117-127).Next: the container in CI, spread-gitlab-ci, the three ways in, image-garden make, allocate and reaching pkgproxy.
Read in the Dockerfile, Makefile, README and .gitlab-ci.yml of image-garden at the pinned commit ("code"). The commands were not run for this map.
docker run --rm -it \ --device /dev/kvm \ --volume $HOME/.cache/image-garden:/var/cache/image-garden \ --volume "$PWD:/src" --workdir /src \ --env PKGPROXY_URL=http://pkgproxy.example.lan:3142 \ registry.gitlab.com/zygoon/image-garden:v0.8.0 \ image-garden make ubuntu-cloud-24.04.x86_64.run
podman run takes the same options. Leave out PKGPROXY_URL when you have no pkgproxy.
| Option | Why |
|---|---|
--device /dev/kvm | hardware acceleration; without it QEMU emulates the CPU, many times slower |
--volume …:/var/cache/image-garden | keeps downloaded images; the image sets GARDEN_CACHE_DIR there and declares it a volume |
--volume "$PWD:/src" --workdir /src | makes your project the working directory, so .image-garden.mk is read and files land there |
--env PKGPROXY_URL=… | a pkgproxy for image downloads and for the guests |
-it | an interactive terminal, for a .run script's serial console |
| Part | Where |
|---|---|
QEMU 11.1.3 with the guestfwd patch, six system emulators and qemu-img | /usr/local |
image-garden and image-garden.mk | /usr/local |
| make, curl, xorriso, xz, git, git-restore-mtime | Ubuntu packages |
| swtpm and OVMF (Secure Boot firmware) | Ubuntu packages |
| the cache | /var/cache/image-garden, a volume |
Not included: spread, pkgproxy, an entrypoint.
The image is published at registry.gitlab.com/zygoon/image-garden with each release's tag, such as v0.8.0, and latest for the newest release, for x86_64 and aarch64 hosts (.gitlab-ci.yml:1257-1278).
image-garden asks a pkgproxy for each image by its checksum before going to the image's own URL. pkgproxy fetches it from the internet once, for every machine that uses it; the origin is the fallback, and the hash is checked either way.
fetch_image asks pkgproxy first when one is named and the checksum is known: "pkgproxy keeps a file by its checksum, so every machine that uses it downloads each image from the internet once" (image-garden:272-280).https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img, checked against the SHA256SUMS next to it (ubuntu.ini:237-242).GARDEN_DL_PKGPROXY wins, and empty turns it off; then PKGPROXY_URL; then, in the snap, the pkgproxy its guests use. A socket that does not exist means none. A socket can be named as unix:/path/to/pkgproxy.sock.
GARDEN_DL_PKGPROXY, when set, is used as it is; set but empty, it turns pkgproxy off for downloads. Unset, it becomes PKGPROXY_URL; unset too, and in the snap, it follows $SNAP_COMMON/pkgproxy-mode: external gives the URL in $SNAP_COMMON/pkgproxy-url, component gives unix:$SNAP_COMMON/pkgproxy.sock, snap gives unix:$SNAP_COMMON/pkgproxy-host-snap/sockets/pkgproxy.sock. A unix: path that is not a socket is dropped without a message (image-garden:31-59).pkgproxy-mode when neither variable is set: in the snap, PKGPROXY_URL in the environment wins over the pkgproxy setting for downloads.unix:PATH is reached with curl --unix-socket PATH at http://pkgproxy; any other value is a base URL, its trailing slash dropped (image-garden:121-136).PKGPROXY_URL set use that pkgproxy too, also outside the snap" (README.md:246-248). GARDEN_DL_PKGPROXY affects downloads only.GARDEN_DL_PKGPROXY=http://127.0.0.1:3142 on the runner, whichever mode its guests use (action.yaml:375-393).GET /files/v1/fetch?url=…&sha256=HASH, one try, a 10 second connect timeout. On failure, Cannot download through pkgproxy, downloading URL directly; the direct download resumes the .partial file. The hash is checked either way.
files/v1/fetch?url=URL&KIND=HEX, with the URL percent-encoded and KIND sha256 or sha512 (image-garden:281-289, image-garden:94-105).--connect-timeout 10 --continue-at -, without --retry: "a pkgproxy that is down, which answers 503 that --retry would retry, or a file that does not match its checksum, which pkgproxy ends short each time, are not worth waiting for" (image-garden:290-301).Cannot download through pkgproxy, downloading URL directly, then downloads from the URL with --retry 5 --retry-connrefused --continue-at - into the same .partial file, resuming a transfer that ends short up to five times (image-garden:302-327).sha256sum --check after (image-garden:542-545).download command passes none and goes to the URL (image-garden:287, image-garden:651). Every image and firmware rule in the tree uses a download-with-… command.tests/dl-pkgproxy-server.py in its 503 mode; URL and hash shortened.Checksum lists come from /files/v1/volatile?url=…: pkgproxy asks the origin each time and keeps the last copy. While the origin is down it gives that copy, and image-garden logs when it was fetched.
fetch_volatile asks /files/v1/volatile?url=URL with one try and --connect-timeout 10, without --fail, keeping the response headers to tell what answered (image-garden:195-240). It is used for SHA512SUMS and SHA256SUMS lists (image-garden:386, image-garden:488); a system with a single SHA256SUM hash has no list to fetch.X-Pkgproxy-Cache: stale prints Using the copy of URL that pkgproxy kept, fetched at TIME, while the origin is down, the time from X-Pkgproxy-Fetched (image-garden:249-254). The line on the slide was produced by running the helper against tests/dl-pkgproxy-server.py in its stale mode, with the URL shortened.https://cloud-images.ubuntu.com/noble/current/SHA256SUMS (ubuntu.ini:237-242); current follows the newest build, which is why the list changes.Unreachable, no volatile files, or a refusal: the list comes from the origin. The origin's own error, passed on by pkgproxy, or a 502 or 503 with no copy kept: the download fails, as a direct one would.
/files/v1/volatile (image-garden:241-269):| pkgproxy's answer | Message | Then |
|---|---|---|
| no connection, or a cut answer (curl fails) | Cannot reach pkgproxy, downloading URL directly | the origin; remembered when curl says 6, 7 or 28 |
| 200 | (the stale-copy line, when it is one) | the list is used |
no X-Pkgproxy-Engine: files-volatile header (a pkgproxy too old for volatile files) | pkgproxy has no volatile files, downloading URL directly | the origin |
X-Pkgproxy-Origin-URL present (the origin's own answer, such as 404) | Cannot download URL: the origin answered HTTP N through pkgproxy | fails, status 22 |
| 502 or 503 from files-volatile | Cannot download URL: pkgproxy cannot reach the origin and kept no copy (HTTP N) | fails, status 22 |
| any other code, such as 403 (a host it does not fetch from, a private address, a file too large) or 500 | pkgproxy does not give URL (HTTP N), downloading it directly | the origin |
curl --fail --location --retry 3 (image-garden:269).FILE.sha256sums.partial and returns the status (image-garden:496-503); make stops on that recipe.tests/dl-pkgproxy-server.py in its fail, old, refused, forbidden and unreachable modes; the 404 line is the same code path as the 403 the server gives in forbidden mode.Next: the download helper, caching on GitHub, the GitLab components' shared pkgproxy, why pkgproxy, an unreachable pkgproxy and the snap setting.
Read in the image-garden script and README.md of image-garden at the commit this map describes ("code"). The messages were produced by running the download-with-sha256sums helper of v0.8.0, whose download code that commit leaves as it was, against the project's own fake pkgproxy, tests/dl-pkgproxy-server.py, in each of its modes, and against a closed port ("run"). How pkgproxy itself stores files is pkgproxy's design and is not described here.
| Set | Downloads go through |
|---|---|
GARDEN_DL_PKGPROXY=http://host:port | that pkgproxy |
GARDEN_DL_PKGPROXY=unix:/path/to/pkgproxy.sock | the pkgproxy listening on that socket |
GARDEN_DL_PKGPROXY= (set, empty) | no pkgproxy |
PKGPROXY_URL=http://host:port, GARDEN_DL_PKGPROXY unset | that pkgproxy |
neither, in the snap, pkgproxy=http://… | the URL from $SNAP_COMMON/pkgproxy-url |
neither, in the snap, pkgproxy=component (default) | unix:$SNAP_COMMON/pkgproxy.sock, if that socket exists |
neither, in the snap, pkgproxy=snap | unix:$SNAP_COMMON/pkgproxy-host-snap/sockets/pkgproxy.sock, if it exists |
| neither, outside the snap | no pkgproxy |
Source: image-garden:31-59.
| What | Request | Tries | Falls back to the origin |
|---|---|---|---|
| an image with a known checksum | GET /files/v1/fetch?url=URL&sha256=HEX (or sha512=) | one, --connect-timeout 10, --continue-at - | on any failure but an interrupt |
a checksum list (SHA256SUMS, SHA512SUMS) | GET /files/v1/volatile?url=URL | one, --connect-timeout 10 | unless the origin's own error or a 502/503 came back through pkgproxy |
The URL is percent-encoded (image-garden:94-105). Images: image-garden:272-327. Lists: image-garden:195-269. A pkgproxy socket is reached with curl --unix-socket at http://pkgproxy (image-garden:121-136).
| Message | Meaning |
|---|---|
Downloading through pkgproxy at ADDRESS | the list or image is asked from pkgproxy first |
Using the copy of URL that pkgproxy kept, fetched at TIME, while the origin is down | the list is pkgproxy's last copy |
Cannot download through pkgproxy, downloading URL directly | the image did not come through pkgproxy; the origin is used, resuming the partial file |
Cannot reach pkgproxy, downloading URL directly | no connection, or a cut answer, for a list |
pkgproxy has no volatile files, downloading URL directly | the pkgproxy is too old for volatile files |
pkgproxy does not give URL (HTTP N), downloading it directly | pkgproxy refused the list (403) or failed otherwise |
Cannot download URL: the origin answered HTTP N through pkgproxy | the origin's own error; the download fails |
Cannot download URL: pkgproxy cannot reach the origin and kept no copy (HTTP N) | 502 or 503 with no copy; the download fails |
Not asking pkgproxy at ADDRESS again for 5 minutes | see an unreachable pkgproxy |
Skipping pkgproxy at ADDRESS, unreachable recently, downloading URL directly | see an unreachable pkgproxy |
Images by checksum need pkgproxy 0.12 or later (README.md:234-240). A pkgproxy without volatile files is detected by the missing X-Pkgproxy-Engine: files-volatile header and skipped for lists (image-garden:255-256).
The guest speaks TCP to 10.0.2.100:3142; the snap's pkgproxy listens on a unix socket. qemu-patches/guestfwd-unix-socket.patch lets QEMU join the two.
pkgproxy -addr pkgproxy:3142 -socket-path $SNAP_COMMON/pkgproxy.sock … (snapcraft.yaml:241); -addr only names it in pkgproxy's printed banner, "binding is over the UNIX socket" (proxy/README.md:50-55).guestfwd forwards guest TCP connections to 10.0.2.100 on port 3142 straight to that UNIX socket … one fresh UNIX connection per guest TCP connection, handled natively inside QEMU" (proxy/README.md:16-23).unix: form of guestfwd isn't a stock QEMU feature" (proxy/README.md:25-33). The patch is qemu-patches/guestfwd-unix-socket.patch.cmd: starts a process per connection (the old nc -U bridge); a chardev shares one host connection between all guest connections. Neither gives one socket connection per guest connection.
cmd:command (spawn a process per connection) and a generic chardev form (one connection shared across *all* guest connections — wrong for HTTP) were reachable" (proxy/README.md:25-31).nc -U per connection via guestfwd=...-cmd:...; the patch removes that external-process dependency entirely" (proxy/README.md:34-36).unix:/path already falls through to the chardev path (qemu_chr_new_mux_mon), which "opens one chardev shared across the whole config-line's lifetime, multiplexing every guest TCP connection onto a single host-side connection — wrong for a protocol like HTTP where concurrent requests need independent connections" (guestfwd-unix-socket.patch:15-20).SOCKET on the slide stands for the socket's path.A unix: branch in net/slirp.c passes the path, guest address and port to libslirp's slirp_add_unix(), which connects afresh for every guest connection.
net/slirp.c at line 1153 of the QEMU source the snap and the container build, between the cmd: branch and the chardev fallback (guestfwd-unix-socket.patch:22-36). &p[5] is the text after unix:, the socket path; server and port are, by libslirp's slirp_add_unix() signature, the guest address and port from tcp:10.0.2.100:3142 (derived: QEMU's net/slirp.c and libslirp are not in the trees this map reads).cmd: branch's, shown as the context line above the hunk (guestfwd-unix-socket.patch:24-27).patch -p1 from the QEMU source directory.The snap's qemu part and the container's build-qemu stage both run patch -p1 with qemu-patches/guestfwd-unix-socket.patch. A distribution's QEMU lacks it.
qemu part, from the release tarball with a pinned source-checksum; override-pull runs craftctl default and then patch -p1 < "${CRAFT_PROJECT_DIR}"/qemu-patches/guestfwd-unix-socket.patch (snapcraft.yaml:327-341). The patch is "applied to all bundled QEMU system-emulator parts" (proxy/README.md:32-33).build-qemu stage adds the same tarball with ADD --checksum=sha256:5a8289c7… (Dockerfile:5-6), then "The same patch as the snap's QEMU", COPY qemu-patches/guestfwd-unix-socket.patch /src/ and RUN patch -d /src/qemu-11.1.3 -p1 </src/guestfwd-unix-socket.patch, before configure (Dockerfile:28-36). The container's NEWS records it under 0.7.0 (NEWS.docker:18-21).5a8289c7… in both files).Outside the snap, pkgproxy is reached by URL, which needs no patch. The smoke test skips the socket modes when the QEMU binary does not mention slirp_add_unix.
pkgproxy.sock in $SNAP_COMMON or $SNAP_COMMON/pkgproxy-host-snap/sockets (010-qemu.mk:20-23, :31). snapd sets SNAP_COMMON for the snap's apps; outside the snap it is unset unless you set it, as image-garden's own tests do with a fixture directory (derived from check-pkgproxy-config.sh:103-120).make PKGPROXY_URL=http://host:port ... does the same, and so does PKGPROXY_URL in the environment" (proxy/README.md:122-127). With a URL make adds no guestfwd (010-qemu.mk:24-30).component and snap: "The patch is the only caller of slirp_add_unix in QEMU", grep -q slirp_add_unix "$qemu", else SKIP: $mode needs QEMU patched with qemu-patches/guestfwd-unix-socket.patch; … is not and exit 77 (smoke-pkgproxy.sh:84-90). A QEMU linked to a shared libslirp names the function it imports, so the name is in the binary only when something calls it (derived).unix:PATH falls through to the chardev path: one host connection shared by every guest connection, per the patch's description (guestfwd-unix-socket.patch:15-20). image-garden itself sets up the socket modes only in the snap, whose QEMU has the patch.PKGPROXY_URL names" (proxy/README.md:7-12).tests/check-pkgproxy-config.sh checks the guestfwd options without booting; tests/smoke-pkgproxy.sh MODE SYSTEM.ARCH boots a guest per mode; the snap's spread suite runs the smoke test nested.
tests/check-pkgproxy-config.sh "Check[s] what image-garden generates for each way of choosing a pkgproxy, without booting anything", with $SNAP_COMMON a fixture directory and "plain files standing in for pkgproxy's sockets" (check-pkgproxy-config.sh:5-9). Its cases: component with and without the LXD socket, component down, snap, snap disconnected, external with and without a port, an unresolvable URL, PKGPROXY_URL from the environment, none and nothing (check-pkgproxy-config.sh:115-170). It also checks the user-data of six families with tests/check-pkgproxy-user-data.py.tests/smoke-pkgproxy.sh MODE SYSTEM.ARCH, MODE one of component, snap, url, none, runs pkgproxy on the host and boots one VM (smoke-pkgproxy.sh:5-23); "It checks the guest's setup, and that what the guest downloads ends up in pkgproxy's cache, or, for none, does not" (proxy/README.md:247-253).tests/snap/ runs tests/smoke-pkgproxy.sh with SMOKE_SNAP=1 for each mode, "with the guest nested in the VM"; it runs only when named (proxy/README.md:261-274).Next: reaching pkgproxy, a distribution QEMU, the container, the snap and why pkgproxy at all.
Read in qemu-patches/guestfwd-unix-socket.patch, snap/snapcraft.yaml, Dockerfile, mk/010-qemu.mk, proxy/README.md and tests/ of image-garden at the v0.8.0 tag ("code"). QEMU's net/slirp.c and libslirp are not in the trees this map reads: what the slides say about them comes from the patch's description and proxy/README.md, and the rest is labelled "derived".
Target after tcp:ADDR:PORT- | In stock QEMU | With the patch | Host side |
|---|---|---|---|
cmd:COMMAND | yes | yes | a new process per guest connection |
unix:PATH | read as a chardev | the patch's branch | a new socket connection per guest connection |
| a chardev | yes | yes | one connection shared by every guest connection |
The snap's .run scripts use guestfwd=tcp:10.0.2.100:3142-unix:$SNAP_COMMON/pkgproxy.sock, and …:3143-unix:…/pkgproxy-lxd-tls.sock when that socket exists (010-qemu.mk:31-39).
--- a/net/slirp.c
+++ b/net/slirp.c
@@ -1153,6 +1153,12 @@
"forwarding rule '%s'", config_str);
return -1;
}
+ } else if (g_str_has_prefix(p, "unix:")) {
+ if (slirp_add_unix(s->slirp, &p[5], &server, port) < 0) {
+ error_setg(errp, "Conflicting/invalid host:port in guest "
+ "forwarding rule '%s'", config_str);
+ return -1;
+ }
} else {
Source: guestfwd-unix-socket.patch:22-36.
| Install | QEMU | Patch | pkgproxy reached by |
|---|---|---|---|
| the snap | built in the qemu part, one build for every QEMU component | applied in override-pull (snapcraft.yaml:327-341) | a socket (the default) or a URL |
| the container | built in the build-qemu stage, installed in /usr/local | applied before configure (Dockerfile:28-32) | PKGPROXY_URL |
| native packages, a source install | the distribution's | not applied | PKGPROXY_URL |
The smoke test's check, usable by hand: grep -q slirp_add_unix "$(command -v qemu-system-x86_64)" succeeds only for a patched QEMU, since "The patch is the only caller of slirp_add_unix in QEMU" (smoke-pkgproxy.sh:84-90).
Every guest asks for pkgproxy. make decides what the name means: a QEMU guestfwd to a unix socket on the host, or the address of a pkgproxy at a URL.
pkgproxy on port 3142 for the sockets, or the URL's port; make chooses the address when it makes a system's files (010-qemu.mk:15-44).guestfwd forwards guest TCP connections to 10.0.2.100 on port 3142 straight to that UNIX socket" (proxy/README.md:16-23).pkgproxy in /etc/hosts (proxy/README.md:117-120). "Whichever pkgproxy it is, guests know it as pkgproxy" (proxy/README.md:129-130).-netdev user, libslirp) gives the guest a private address range and translates its outgoing connections into connections made by the QEMU process on the host (derived: general QEMU behaviour).A URL, from PKGPROXY_URL or snap set image-garden pkgproxy=http://…, wins. Else an existing pkgproxy socket is bridged. Else the guest gets no pkgproxy.
snap set image-garden pkgproxy=… into a mode (component, snap, external or none) and, for a URL, checks it against ^http://[A-Za-z0-9.-]+(:[0-9]+)?/?$ (configure:17-39). It writes the mode to $SNAP_COMMON/pkgproxy-mode and the URL to $SNAP_COMMON/pkgproxy-url (configure:76-82).external; PKGPROXY_URL ?= … means a PKGPROXY_URL from the environment or the command line takes precedence over the saved URL (010-qemu.mk:20-21). That a PKGPROXY_URL in the snap's environment also overrides the component, snap and none modes follows from the same line (derived, not run).$SNAP_COMMON, or $SNAP_COMMON/pkgproxy-host-snap/sockets in snap mode, where snapd mounts the pkgproxy snap's sockets slot (010-qemu.mk:22-23). The bridge is set up only when pkgproxy.sock exists there (010-qemu.mk:31-39).$SNAP_COMMON is empty, so make looks for /pkgproxy-mode and /pkgproxy.sock at the file system's root, which normally do not exist: PKGPROXY_URL is the only setting there (derived from the same lines).-netdev user,guestfwd=tcp:10.0.2.100:3142-unix:$SNAP_COMMON/pkgproxy.sock: one host connection per guest connection, written into the .run script.
pkgproxy.sock in the socket directory, make sets PKGPROXY_GUEST_IP := 10.0.2.100, PKGPROXY_PORT := 3142 and QEMU_DEFAULT_NETDEV_SYS_EXTRA = ,guestfwd=tcp:10.0.2.100:3142-unix:$(PKGPROXY_SOCKET_DIR)/pkgproxy.sock, and adds ,guestfwd=tcp:10.0.2.100:3143-unix:…/pkgproxy-lxd-tls.sock when that socket exists too (010-qemu.mk:31-39).-netdev user,id=netdev0$(QEMU_DEFAULT_NETDEV_SYS_EXTRA)${QEMU_NETDEV_USER_EXTRA:-} (010-qemu-x86_64.mk:8-11). The first part is expanded when the .run script is written; QEMU_NETDEV_USER_EXTRA is read when it runs.image-garden make -n ubuntu-cloud-24.04.x86_64.run with a fixture $SNAP_COMMON holding a pkgproxy.sock printed -netdev user,id=netdev0,guestfwd=tcp:10.0.2.100:3142-unix:<fixture>/pkgproxy.sock${QEMU_NETDEV_USER_EXTRA:-}.curl -fsSL http://pkgproxy:3142/setup/lxd-remote | sh in a guest does (proxy/README.md:76-88).10.0.2.100 is inside the user network's default 10.0.2.0/24 range but is no machine: libslirp answers it with the forwarding rule (derived: general QEMU behaviour). The snap's $SNAP_COMMON is /var/snap/image-garden/common (derived: snapd's layout).$SNAP_COMMON on the slide stands for the directory: the .run script holds the expanded path..run script.http://host[:port], port 80 by default. make resolves the host with getent ahostsv4 and the guest gets that address as pkgproxy in /etc/hosts. No guestfwd.
^http://([A-Za-z0-9.-]+)(:[0-9]+)?/?$ and the port from the same pattern, or 80 (010-qemu.mk:24-26), then "/etc/hosts maps names to addresses only, so resolve the host now": getent ahostsv4 HOST, the first address (010-qemu.mk:27-28). No guestfwd is added (010-qemu.mk:30).grep -q '^IP pkgproxy$' /etc/hosts || { echo '# image-garden: pkgproxy, see http://pkgproxy:PORT/'; echo 'IP pkgproxy'; } >>/etc/hosts, in bootcmd and in runcmd (010-qemu.mk:132-134). Run for this deck: with PKGPROXY_URL=http://192.0.2.9:3142, ubuntu-cloud-24.04.x86_64.user-data differs from the socket mode's only in 192.0.2.9 replacing 10.0.2.100 on those two lines.pkgproxy.example.lan is the README's example name (proxy/README.md:103-104); 192.0.2.9 is a documentation address.make PKGPROXY_URL=http://host:port ... does the same, and so does PKGPROXY_URL in the environment" (proxy/README.md:117-127). The same variable sends image downloads through that pkgproxy unless GARDEN_DL_PKGPROXY says otherwise: see image downloads.-lxd-tls-addr names (proxy/README.md:120-122).127.0.0.1 and localhost mean the guest itself. Use the host's network address, or 10.0.2.2, the host's loopback as the guest sees it.
/etc/hosts (010-qemu.mk:24-28); localhost resolves to 127.0.0.1, which in the guest is the guest's own loopback (derived).host_ip="$(hostname -I | awk '{ print $1 }')" and snap set image-garden pkgproxy=http://"$host_ip":3142 (action.yaml:386-389). Its own image downloads, made on the host, use GARDEN_DL_PKGPROXY=http://127.0.0.1:3142 (action.yaml:391-393).127.0.0.1:PORT and gives guests http://10.0.2.2:PORT: "QEMU's user networking makes the host's loopback 10.0.2.2" (smoke-pkgproxy.sh:229-233).127.0.0.1 does work, so the downloads may be cached while the guests are not (derived).host-gateway: see an address the VM can reach.An https URL or a host that does not resolve: cannot use pkgproxy at "…": … guests get no pkgproxy. A missing socket: no message. Both are baked into the files make wrote.
PKGPROXY_URL does not match http://host[:port] or its host has no IPv4 address, make prints cannot use pkgproxy at "URL": want http://host[:port] with a host that resolves to IPv4; guests get no pkgproxy with $(warning …) (010-qemu.mk:24-29). Run for this deck with https://192.0.2.9:3142 and with http://pkgproxy.invalid:3142: both print it, prefixed with the make file and line, and leave PKGPROXY_GUEST_IP empty.pkgproxy must be component, snap, none or a URL such as http://192.0.2.1:3142 (configure:28-38). A name that stops resolving later still gets the warning.pkgproxy=snap set while the plug is disconnected, the configure hook says pkgproxy=snap, but the pkgproxy snap's sockets are not connected: guests get no pkgproxy until snap connect … once, when the setting is applied (configure:56-68); make itself says nothing..user-data and .run rules do not depend on the pkgproxy setting, so they are not made again by themselves: see changing the proxy does not rebuild.Next: the user-data, the guestfwd patch, addresses from a CI container, the container's PKGPROXY_URL, an unreachable pkgproxy and rebuilding.
Read in mk/010-qemu.mk, snap/hooks/configure, proxy/README.md and tests/ of image-garden at the v0.8.0 tag ("code"). The QEMU option and the user-data lines were produced by running image-garden make from an export of that tag with a fixture $SNAP_COMMON, as tests/check-pkgproxy-config.sh does, and with PKGPROXY_URL ("run"). How QEMU's user network treats addresses is general QEMU behaviour ("derived").
| Setting when the files are made | Guest's pkgproxy | Port | QEMU -netdev user gets |
|---|---|---|---|
PKGPROXY_URL=http://host[:port], or pkgproxy=http://… in the snap | the host's first IPv4 address from getent ahostsv4 | the URL's, else 80 | nothing |
a URL that is not http://host[:port], or a host without IPv4 | none, with a warning | - | nothing |
pkgproxy=component (the snap's default), $SNAP_COMMON/pkgproxy.sock exists | 10.0.2.100 | 3142 | ,guestfwd=tcp:10.0.2.100:3142-unix:$SNAP_COMMON/pkgproxy.sock |
pkgproxy=snap, $SNAP_COMMON/pkgproxy-host-snap/sockets/pkgproxy.sock exists | 10.0.2.100 | 3142 | the same, with the pkgproxy snap's socket |
either socket mode, with pkgproxy-lxd-tls.sock beside it | as above | as above | also ,guestfwd=tcp:10.0.2.100:3143-unix:…/pkgproxy-lxd-tls.sock |
| a socket mode whose socket does not exist yet | none, silently | - | nothing |
pkgproxy=none, or nothing set outside the snap | none | - | nothing |
Source: 010-qemu.mk:20-44. PKGPROXY_URL from the environment or the make command line wins over the snap's saved URL and mode (?=, line 21).
| Variable | Set from | Used by |
|---|---|---|
PKGPROXY_MODE | $SNAP_COMMON/pkgproxy-mode | the socket directory and whether the saved URL is read |
PKGPROXY_URL | the environment, the command line, or $SNAP_COMMON/pkgproxy-url in external mode | the URL path, and image downloads |
PKGPROXY_SOCKET_DIR | $SNAP_COMMON, or …/pkgproxy-host-snap/sockets in snap mode | the socket path |
PKGPROXY_HOST, PKGPROXY_PORT | parsed from the URL | the guest's port |
PKGPROXY_GUEST_IP | getent ahostsv4, or 10.0.2.100 | the /etc/hosts line; empty means no pkgproxy |
QEMU_DEFAULT_NETDEV_SYS_EXTRA | the guestfwd rules | every architecture's -netdev user |
QEMU_NETDEV_USER_EXTRA, read by the .run script when it runs, is appended after them (010-qemu-x86_64.mk:8-11).
| Address | In the guest |
|---|---|
127.0.0.1, localhost | the guest itself |
10.0.2.2 | the host's loopback, through the user network (smoke-pkgproxy.sh:230-233) |
10.0.2.100 | pkgproxy's socket, only with a guestfwd rule |
| the host's LAN address | the host, through the user network |
Docker's host-gateway | not defined in the guest (snapcraft-gitlab-ci README.md:218-224) |
snap set image-garden pkgproxy=none changes nothing that make can see: image-garden make keeps the guest built with the bundled pkgproxy. The setting applies to systems made after the change.
none exists mainly for test suites, such as snapd's spread suite, that do not yet expect the injected SNAPPY_FORCE_API_URL or the extra /etc/hosts entries (README.md:211-215, proxy/README.md:134-136).image-garden make ubuntu-cloud-24.04.x86_64.user-data with PKGPROXY_URL set answered make: 'ubuntu-cloud-24.04.x86_64.user-data' is up to date.; the prepared image and the .run script behaved the same way. The snap reads the mode from a file instead of the variable, with the same result (derived from 010-qemu.mk:20-23).PKGPROXY_URL: setting, changing or unsetting it rebuilds nothing.The choice is copied into SYSTEM.user-data (hosts line, setup scripts, GOPROXY, a URL's address) and SYSTEM.run (the guestfwd), and the first boot writes it into the disk. Downloads read the setting each time.
$SNAP_COMMON/pkgproxy-mode, PKGPROXY_URL and whether the socket exists each time it runs (010-qemu.mk:20-44). With a URL, the host is resolved with getent ahostsv4 then, because "/etc/hosts maps names to addresses only" (010-qemu.mk:25-28).bootcmd and runcmd pkgproxy lines and the GOPROXY line of /etc/environment only when a pkgproxy was found (010-qemu.mk:127-185)..run script's default_qemu_net_option is -netdev user,id=netdev0 plus QEMU_DEFAULT_NETDEV_SYS_EXTRA, the guestfwd for the socket modes and nothing for a URL (010-qemu-x86_64.mk:8-11, 010-qemu-x86_64.mk:70); the other architectures' files do the same. With the bundled pkgproxy's LXD socket, a second guestfwd for port 3143 is added (010-qemu.mk:37-39).apt script writes Acquire::http::Proxy to /etc/apt/apt.conf.d/99pkgproxy, and its snap script writes /etc/systemd/system/snapd.service.d/pkgproxy.conf, which sets SNAPPY_FORCE_API_URL (proxy/README.md:171-180).SYSTEM.user-data depends on the makefiles and .image-garden.mk, SYSTEM.run on the makefiles. The mode file and PKGPROXY_URL are not prerequisites. Bundled and snap modes differ only in the .run script's socket path.
SYSTEM.user-data: $(MAKEFILE_LIST) $(wildcard $(GARDEN_PROJECT_DIR)/.image-garden.mk) (rulegen.py:467-471; instances: 020-instances.mk:76). SYSTEM.run: $(MAKEFILE_LIST), with the prepared image and firmware copies as order-only prerequisites, which never make it older (rulegen.py:594-599; instances: 020-instances.mk:87).$(shell cat …) and from the environment (010-qemu.mk:20-23); neither is a prerequisite of any rule.10.0.2.100 and the port 3142; only PKGPROXY_SOCKET_DIR differs, $SNAP_COMMON or $SNAP_COMMON/pkgproxy-host-snap/sockets (010-qemu.mk:22-34). So moving between them needs only a new .run script..run script is also made again whenever image-garden is upgraded, since the makefiles change; the user-data too, and with it the prepared image (see the overlay).Turned off: the old .run forwards to a removed socket and the guest's apt and snapd still use pkgproxy. Turned on: the old guest stays uncached. A URL: the guest keeps the address resolved when it was made.
component stops and disables the bundled daemon and removes pkgproxy.sock, stats.sock and pkgproxy-lxd-tls.sock from $SNAP_COMMON (configure:6-9, configure:56-73).guestfwd opens a new connection to the socket for each guest connection (guestfwd-unix-socket.patch), so the old .run script still boots, and each connection from the guest to 10.0.2.100:3142 fails. apt, with Acquire::http::Proxy set, and snapd, with SNAPPY_FORCE_API_URL set, then fail their downloads rather than going direct./etc/hosts (010-qemu.mk:24-29, proxy/README.md:117-120). 192.0.2.10 is a documentation address.SYSTEM.qcow2 and run image-garden make SYSTEM.qcow2 (proxy/README.md:159-164); see an unreachable pkgproxy.Remove SYSTEM.user-data, SYSTEM.seed.iso and SYSTEM.run, then make the system. Removing only the user-data is not enough. image-garden make clean removes the made files of every system.
touch --reference= the newest of its prerequisites, the makefiles and .image-garden.mk (rulegen.py:467-471); the seed depends on the user-data and meta-data (010-qemu.mk:268), the prepared image on the seed (rulegen.py:601-602).PKGPROXY_URL set after the files were made: removing only ubuntu-cloud-24.04.x86_64.user-data and making it again wrote the new user-data with the time of image-garden.mk, and make then said the .qcow2 and the .run were up to date. Removing the .user-data, the .seed.iso and the .run made make -n list the seed ISO, qemu-img create, the provisioning boot and the launcher script.make -n alone is misleading here: it assumes a remade user-data is new, and lists the seed and the disk even when only the user-data was removed..image-garden/ when that directory exists, else in the current directory (image-garden:987-993).image-garden make clean removes *.log, *.seed.iso, *.meta-data and *.user-data, and each system's .qcow2, .run and its link in the download cache (000-garden.mk:48-50, 010-qemu.mk:300-302, rulegen.py:473-477). The downloaded images stay; the next make checks them again and links them..run script removed (see the previous scenes)..run script without -snapshot is lost (see the overlay).cache-prepared-images keys .image-garden/ by system and hashFiles('.image-garden.mk'). A restored image keeps the mode, snap or external, of the job that made it; changing .image-garden.mk changes the key.
cache-prepared-images: true, the action caches SUBDIR/.image-garden without its logs under the key image-garden-img-GARDEN_SYSTEM-HASH, where HASH is hashFiles('SUBDIR/.image-garden.mk') (action.yaml:116-123). The .user-data, the .seed.iso, the .run script and the prepared .qcow2 are all in it.external mode when ss finds a listener on port 3142, else snap mode (action.yaml:173-188). In snap mode it runs snap set image-garden pkgproxy=snap; in external mode pkgproxy=http://ADDRESS:3142, with the first address of hostname -I, "as 127.0.0.1 would be the guest itself" (action.yaml:375-393)..run script that forwards to the pkgproxy snap's socket, which an external-mode job does not have; one made in external mode has the first runner's address in its /etc/hosts. Even when make provisions the restored image again (see how the action caches), it does so from the restored seed, with the old mode..image-garden.mk, even by a comment, gives a new key; cache-key-prefix names the pkgproxy caches only (action.yaml:30-31).Next: when the disk is made again, where the files live, caching on GitHub, an unreachable pkgproxy, the snap setting and the user-data.
Read in rulegen.py, mk/010-qemu.mk, mk/020-instances.mk, the snap's configure hook and image-garden-action's action.yaml at the pinned commits ("code"). What make rebuilds was checked by running v0.8.0's image-garden make on ubuntu-cloud-24.04.x86_64 in a scratch directory, outside the snap, with PKGPROXY_URL changed after the files were made ("run"). What apt and snapd do in an old guest, and what a restored CI image holds, are reasoned from the code ("derived").
| File | What it holds | Remade when |
|---|---|---|
SYSTEM.user-data | the pkgproxy hosts line with its address, the apt and snap setup lines, GOPROXY | a makefile or .image-garden.mk is newer, or it is missing |
SYSTEM.seed.iso | the user-data and meta-data | the user-data or meta-data is newer, or it is missing |
SYSTEM.qcow2 | after the provisioning boot: /etc/apt/apt.conf.d/99pkgproxy, the snapd drop-in, /etc/hosts, /etc/environment | the seed, the download or the firmware copies are newer, or it is missing |
SYSTEM.run | QEMU's guestfwd to the socket, in socket modes | a makefile is newer, or it is missing |
Sources: rulegen.py:461-471, rulegen.py:594-609, 010-qemu.mk:20-44, 010-qemu.mk:268.
| Change | Remove, then make the system |
|---|---|
component ⇄ snap | SYSTEM.run |
| any other change of mode or URL | SYSTEM.user-data, SYSTEM.seed.iso, SYSTEM.run |
| no change, but pkgproxy could not be reached while the guest was prepared | SYSTEM.qcow2 (proxy/README.md:159-164) |
| every system at once | image-garden make clean |
The files are in .image-garden/ when the project has that directory, otherwise in the directory you run image-garden from (image-garden:987-993). Removing only SYSTEM.user-data remakes it with the makefiles' time, older than the seed, so the seed and the disk are kept (run). A new disk starts empty: see the overlay.
Image downloads choose their pkgproxy on every run, so GARDEN_DL_PKGPROXY, PKGPROXY_URL and the snap setting apply to the next download at once (image-garden:31-59).
Without care, a missing pkgproxy makes every setup script in the guest and every download on the host wait for a timeout. Each side asks once, remembers, and skips the rest.
bootcmd adds the pkgproxy hosts line, then asks http://pkgproxy:3142/ once (curl: 5 s to connect, 20 s in all; wget: 5 s, one try). With no answer it prints why and touches /run/image-garden-pkgproxy-unreachable.
bootcmd runs PKGPROXY_HOSTS_SHELL, then PKGPROXY_PROBE_SHELL, then the apt setup on Debian and Ubuntu (010-qemu.mk:156-162).grep -q '^IP pkgproxy$' /etc/hosts || { echo '# image-garden: pkgproxy, see URL/'; echo 'IP pkgproxy'; } >>/etc/hosts (010-qemu.mk:132-134). 10.0.2.100 is the address with the snap's socket; with a URL it is the URL's resolved address.curl -s -o /dev/null --connect-timeout 5 --max-time 20 URL/, or wget -q -T 5 -t 1 -O /dev/null URL/; on failure, image-garden: cannot reach pkgproxy at URL/, skipping its setup scripts in this boot on standard error, and touch /run/image-garden-pkgproxy-unreachable. A guest with neither tool asks nothing and leaves no file (010-qemu.mk:136-148).ubuntu-cloud-24.04.x86_64 with PKGPROXY_URL set, in a scratch directory.tests/check-pkgproxy-guest-shell.sh, part of make check, runs these lines under dash and busybox sh with stub curl and wget (proxy/README.md:255-259).Both setup batches see the file and print image-garden: pkgproxy was unreachable, skipping setup scripts: apt (or snap). cloud-init is disabled after the provisioning boot, so the image stays uncached until SYSTEM.qcow2 is made again.
PKGPROXY_SETUP_SHELL checks the marker first: image-garden: pkgproxy was unreachable, skipping setup scripts: TOOLS on standard error; otherwise it fetches URL/setup/TOOL with curl -fsSL --connect-timeout 5, or wget, and pipes it to sh (010-qemu.mk:150-154). The apt batch runs from bootcmd on Debian and Ubuntu, the snap batch from runcmd on all but Alpine (010-qemu.mk:127-130, 010-qemu.mk:156-168).runcmd; GOPROXY="URL/go,direct" is appended to /etc/environment by write_files whether or not pkgproxy answers (010-qemu.mk:132-134, 010-qemu.mk:170-180).GOPROXY, the go command moves on to direct only when the proxy answers 404 or 410, so while pkgproxy stays unreachable, module downloads in such a guest fail to connect rather than going direct.runcmd command is touch /etc/cloud/cloud-init.disabled (010-qemu.mk:246); cloud-init does nothing on later boots (see provisioning runs once), so bootcmd does not ask pkgproxy again..run script or allocate, neither ask pkgproxy again nor run the setup scripts. A guest prepared while pkgproxy could not be reached stays uncached until its image is made again: remove SYSTEM.qcow2 and run image-garden make SYSTEM.qcow2" (proxy/README.md:159-164). The comment on the marker file agrees: "Provisioning disables cloud-init at its end, so no later boot asks pkgproxy again" (010-qemu.mk:136-139).SYSTEM.qcow2 is enough here: the user-data already holds the pkgproxy lines, so the new provisioning boot runs the setup scripts again. After a change of pkgproxy setting more files must go: see changing the proxy does not rebuild.curl exit 6, 7 or 28 writes $XDG_RUNTIME_DIR/image-garden/pkgproxy-unreachable.HASH and prints Not asking pkgproxy at URL again for 5 minutes. For 300 seconds every download prints Skipping pkgproxy at URL, unreachable recently, downloading URL directly.
fetch_volatile and fetch_image skip pkgproxy when pkgproxy_skip succeeds (image-garden:216, image-garden:287), and call pkgproxy_unreachable with curl's status after a failed try (image-garden:244-248, image-garden:302-307).$XDG_RUNTIME_DIR/image-garden/pkgproxy-unreachable. followed by the first 16 hex digits of the sha256 of the address without its trailing slash; it holds the address (image-garden:152-161, image-garden:183-193). The hash on the slide is the one for http://pkgproxy.example.lan:3142._pkgproxy_unreachable_ttl=300; a file 300 seconds old or older, or from the future, is ignored (image-garden:150, image-garden:163-176).GARDEN_DL_PKGPROXY set to a closed port in a scratch directory; the address, the hash and the image URL on the slide are the example's. On that host the closed port timed out (28) rather than refusing (7).Cannot reach pkgproxy, downloading URL directly for a list, or Cannot download through pkgproxy, downloading URL directly for an image.Only a failure to resolve, connect or connect in time is remembered, per address. HTTP errors, cut answers and sockets are not. The file lives in $XDG_RUNTIME_DIR/image-garden, else /run/image-garden, and a reboot clears it.
pkgproxy_unreachable_file prints nothing for a unix: address (image-garden:138-161). In the snap, a socket that does not exist is not used at all (image-garden:51-58).XDG_RUNTIME_DIR defaults to /run (image-garden:61-64); in the snap it is /run/user/UID/snap.image-garden, or /run/snap.image-garden where /run/user/UID does not exist (image-garden:66-73). When the directory cannot be made or the file written, nothing is remembered and no message is printed (image-garden:190-192)./run is a tmpfs on systemd systems, which is why a reboot forgets (derived).tests/check-dl-pkgproxy.sh covers each case: remembered, a file 290 and 301 seconds old, one dated an hour ahead, nowhere to remember, another pkgproxy, and HTTP errors not remembered (run at the tag: all pass).Next: provisioning runs once, the craft components, the runtime directory, reaching pkgproxy, image downloads, starting a guest again and the user-data.
Read in mk/010-qemu.mk, the image-garden script and proxy/README.md of image-garden at the commit this map describes ("code"). The guest's lines were taken from a user-data that v0.8.0's image-garden make generated with PKGPROXY_URL set; the host's messages were produced by running the download helper with GARDEN_DL_PKGPROXY at a closed port ("run"). That later boots do not probe again follows from cloud-init being disabled after the provisioning boot ("derived"), and proxy/README.md says so.
| Step | Command | Limit | On failure |
|---|---|---|---|
probe, in bootcmd | curl -s -o /dev/null --connect-timeout 5 --max-time 20 http://pkgproxy:PORT/ | 5 s to connect, 20 s in all | image-garden: cannot reach pkgproxy at URL/, skipping its setup scripts in this boot, then touch /run/image-garden-pkgproxy-unreachable |
| probe without curl | wget -q -T 5 -t 1 -O /dev/null http://pkgproxy:PORT/ | 5 s, one try | the same |
apt setup, in bootcmd (Debian, Ubuntu) | curl -fsSL --connect-timeout 5 URL/setup/apt, piped to sh | 5 s to connect | skipped while the marker exists: image-garden: pkgproxy was unreachable, skipping setup scripts: apt |
snap setup, in runcmd (all but Alpine) | curl -fsSL --connect-timeout 5 URL/setup/snap, piped to sh | 5 s to connect | skipped: image-garden: pkgproxy was unreachable, skipping setup scripts: snap |
Sources: 010-qemu.mk:127-168. A guest with neither curl nor wget asks nothing and leaves no marker; its setup prints image-garden: no curl or wget to fetch URL/setup/TOOL.
Only the provisioning boot runs any of this: a guest prepared while pkgproxy could not be reached stays uncached until SYSTEM.qcow2 is removed and made again (proxy/README.md:159-164).
Written regardless of the probe: the pkgproxy line in /etc/hosts and GOPROXY="URL/go,direct" in /etc/environment (010-qemu.mk:132-134, 010-qemu.mk:170-180).
| Item | Value |
|---|---|
| tries per download | one, --connect-timeout 10 |
| remembered curl statuses | 6 (resolve), 7 (connect), 28 (timeout) |
| file | $XDG_RUNTIME_DIR/image-garden/pkgproxy-unreachable.HASH16, the address inside |
XDG_RUNTIME_DIR unset | /run |
| in the snap | /run/user/UID/snap.image-garden, or /run/snap.image-garden |
| lifetime | 300 seconds by the file's time; a file from the future is ignored |
sockets (unix:) | never remembered |
| directory not writable | nothing remembered, no message |
Sources: image-garden:61-73, image-garden:138-193.
| Message | When |
|---|---|
Cannot reach pkgproxy, downloading URL directly | a list's try failed to connect |
Cannot download through pkgproxy, downloading URL directly | an image's try failed |
Not asking pkgproxy at ADDRESS again for 5 minutes | the failure was 6, 7 or 28 and the file was written |
Skipping pkgproxy at ADDRESS, unreachable recently, downloading URL directly | a later download within 300 seconds |
With a pkgproxy, ubuntu-cloud-24.04.x86_64.user-data gains a bootcmd block, an /etc/environment entry in write_files and a runcmd item. The apt and snapd settings come from pkgproxy's own setup scripts.
$(call PKGPROXY_CLOUD_INIT_BOOTCMD,$1) after ssh_pwauth, $(INJECTED_CLOUD_INIT_FILES) at the end of write_files and $(call PKGPROXY_CLOUD_INIT_RUNCMD,$1) before the last runcmd item, which creates /etc/cloud/cloud-init.disabled (010-qemu.mk:187-247). Without a pkgproxy all three are empty (010-qemu.mk:181-185).tests/check-pkgproxy-user-data.py checks that image-garden writes no apt or snapd configuration of its own.image-garden make ubuntu-cloud-24.04.x86_64.user-data with a fixture socket, and again with nothing set; the two files differ only in the three places.PKGPROXY_URL, and 3142 with the snap's sockets (010-qemu.mk:128).10.0.2.100 pkgproxy (or the URL's address) goes into /etc/hosts in bootcmd and again in runcmd, unless it is there. Scripts come from http://pkgproxy:PORT/setup/TOOL.
PKGPROXY_HOSTS_SHELL: "A shell line that adds pkgproxy to /etc/hosts unless it is there. It runs from runcmd as well, in case cloud-init rewrote /etc/hosts since bootcmd" (010-qemu.mk:132-134). It is the first line of the bootcmd block and of the runcmd item (010-qemu.mk:156-168).ubuntu-cloud-24.04.x86_64.user-data made with a fixture socket; with PKGPROXY_URL=http://192.0.2.9:3142 only the address changes.PKGPROXY_GUEST_URL = http://pkgproxy:$(PKGPROXY_PORT) (010-qemu.mk:128).PKGPROXY_SETUP_SHELL fetches each script with curl -fsSL --connect-timeout 5 http://pkgproxy:PORT/setup/"$tool" | sh, or wget -q -T 5 -O - … | sh, or prints image-garden: no curl or wget to fetch … (010-qemu.mk:150-154). "Only the connection has a short timeout: the scripts are small, but the network may be slow."/root/hosts.APPEND, which maps the guest's host name to 127.0.0.1, is appended in runcmd too, before the pkgproxy item (010-qemu.mk:231-245).On Debian and Ubuntu, bootcmd probes pkgproxy once, then runs /setup/apt, which writes Acquire::http::Proxy to /etc/apt/apt.conf.d/99pkgproxy before cloud-init installs packages.
PKGPROXY_BOOTCMD_SETUP = $(if $(filter debian ubuntu,$1),apt) (010-qemu.mk:129). It "runs from bootcmd, early in the first boot, so that cloud-init's own package installs (packages: in a custom template) already go through pkgproxy" (010-qemu.mk:114-116).http://pkgproxy:PORT/ once and, without an answer, leaves /run/image-garden-pkgproxy-unreachable, so that neither batch waits again in that boot (010-qemu.mk:122-126): see an unreachable pkgproxy.Acquire::http::Proxy to /etc/apt/apt.conf.d/99pkgproxy" (proxy/README.md:171-174). The script itself is pkgproxy's, served by the running daemon; its exact content is in pkgproxy's tree, not image-garden's.sources.list mirror URLs and point Acquire::http::Proxy at the proxy" (proxy/README.md:40-41).https:// to http:// in every *.list and deb822 *.sources file under /etc/apt, with or without a pkgproxy, so that what apt fetches is plain http that pkgproxy can cache (010-qemu.mk:244); see SSH logins and apt sources.On every family but Alpine, runcmd runs /setup/snap: a drop-in for snapd.service with SNAPPY_FORCE_API_URL, written even before snapd is installed, and a restart of snapd where it is.
PKGPROXY_RUNCMD_SETUP = $(if $(filter alpine,$1),,snap) (010-qemu.mk:130). "PKGPROXY_RUNCMD_SETUP runs from runcmd, at the end of the first boot. The snap script restarts snapd, which must not happen from bootcmd: systemctl waits for the restart, and snapd may be ordered after cloud-init's early stages" (010-qemu.mk:117-120). That the wait would hold up the boot is the slide's reading of that comment (derived).touch /etc/cloud/cloud-init.disabled (010-qemu.mk:245-246)./etc/systemd/system/snapd.service.d/pkgproxy.conf) that sets SNAPPY_FORCE_API_URL, also where snapd is installed later, and restarts snapd where it is installed" (proxy/README.md:175-180). snapd is "pointed at the proxy directly, as if it were the store … not a traditional proxy setting" (proxy/README.md:42-44).pkgproxy=none exists mainly for snapd's own spread suite, where some tests are not yet adjusted for the injected SNAPPY_FORCE_API_URL or the extra /etc/hosts entries (proxy/README.md:134-136).write_files appends GOPROXY="http://pkgproxy:3142/go,direct" to /etc/environment, which PAM reads for every SSH session, before and after Go is installed.
write_files entry is INJECTED_CLOUD_INIT_FILES (010-qemu.mk:174-180).go env -w, which pkgproxy's script uses, "only writes the invoking user's own $GOENV"; /etc/environment is read by PAM (pam_env, enabled by the template's UsePam yes sshd setting) for every SSH session (proxy/README.md:192-202, 010-qemu.mk:212-220).,direct keeps modules pkgproxy can't serve reachable from their source "once GOPRIVATE excludes them" (proxy/README.md:200-202). In Go's GOPROXY list a comma moves to the next entry only when the proxy answers 404 or 410 (derived: Go's documented behaviour).PKGPROXY_URL; 3142 with the snap's sockets.Debian, Ubuntu: hosts, apt, snap, GOPROXY. Other families: hosts, snap, GOPROXY. Alpine: hosts, GOPROXY. Ubuntu Core: none. A project's .image-garden.mk may redefine PKGPROXY_BOOTCMD_SETUP and PKGPROXY_RUNCMD_SETUP.
PKGPROXY_BOOTCMD_SETUP = $(if $(filter debian ubuntu,$1),apt) and PKGPROXY_RUNCMD_SETUP = $(if $(filter alpine,$1),,snap) (010-qemu.mk:129-130). The scripts are picked per family because "pkgproxy's setup scripts do nothing where their tool is missing, but there is no one script for a whole guest yet (zygoon/pkgproxy#92)" (010-qemu.mk:110-112).data/*.ini are almalinux, alpine, amazonlinux, archlinux, centos, debian, fedora, gentoo, opencloudos, opensuse, oracle, rocky and ubuntu; all but alpine, debian and ubuntu get the "other families" row..image-garden.mk can override either variable; $1 is the guest's group, such as debian or fedora" (proxy/README.md:182-184). The example on the slide is illustrative, not taken from the tree; an empty result leaves the setup line out of that block.BASE_UBUNTU_CORE_CLOUD_INIT_USER_DATA_TEMPLATE, which has no pkgproxy lines (050-ubuntu-core.mk:131-179).tests/check-pkgproxy-config.sh checks one system of each of debian, ubuntu, fedora, alpine, amazonlinux and opensuse (check-pkgproxy-config.sh:24-25).Next: reaching pkgproxy, an unreachable pkgproxy, the common template, your .image-garden.mk and why made images keep their setup.
Read in mk/010-qemu.mk, mk/050-ubuntu-core.mk and proxy/README.md of image-garden at the v0.8.0 tag ("code"). The excerpts below were produced by running image-garden make ubuntu-cloud-24.04.x86_64.user-data from an export of that tag, once with a fixture $SNAP_COMMON holding pkgproxy.sock and once with nothing set ("run"). What pkgproxy's setup scripts write is from proxy/README.md: the scripts are served by pkgproxy and are not in image-garden's tree.
With the snap's socket (10.0.2.100, port 3142). With PKGPROXY_URL=http://192.0.2.9:3142, only the address on the two hosts lines changes.
bootcmd:
- |
grep -q '^10.0.2.100 pkgproxy$' /etc/hosts || { echo '# image-garden: pkgproxy, see http://pkgproxy:3142/'; echo '10.0.2.100 pkgproxy'; } >>/etc/hosts
if command -v curl >/dev/null 2>&1; then curl -s -o /dev/null --connect-timeout 5 --max-time 20 http://pkgproxy:3142/; elif command -v wget >/dev/null 2>&1; then wget -q -T 5 -t 1 -O /dev/null http://pkgproxy:3142/; fi || { echo "image-garden: cannot reach pkgproxy at http://pkgproxy:3142/, skipping its setup scripts in this boot" >&2; touch /run/image-garden-pkgproxy-unreachable; }
if [ -e /run/image-garden-pkgproxy-unreachable ]; then echo "image-garden: pkgproxy was unreachable, skipping setup scripts: apt" >&2; else for tool in apt; do if command -v curl >/dev/null 2>&1; then curl -fsSL --connect-timeout 5 http://pkgproxy:3142/setup/"$tool" | sh; elif command -v wget >/dev/null 2>&1; then wget -q -T 5 -O - http://pkgproxy:3142/setup/"$tool" | sh; else echo "image-garden: no curl or wget to fetch http://pkgproxy:3142/setup/$tool" >&2; fi; done; fi
write_files:
...
- path: /etc/environment
permissions: '0644'
append: true
content: |
GOPROXY="http://pkgproxy:3142/go,direct"
runcmd:
...
- |
grep -q '^10.0.2.100 pkgproxy$' /etc/hosts || { echo '# image-garden: pkgproxy, see http://pkgproxy:3142/'; echo '10.0.2.100 pkgproxy'; } >>/etc/hosts
if [ -e /run/image-garden-pkgproxy-unreachable ]; then echo "image-garden: pkgproxy was unreachable, skipping setup scripts: snap" >&2; else for tool in snap; do if command -v curl >/dev/null 2>&1; then curl -fsSL --connect-timeout 5 http://pkgproxy:3142/setup/"$tool" | sh; elif command -v wget >/dev/null 2>&1; then wget -q -T 5 -O - http://pkgproxy:3142/setup/"$tool" | sh; else echo "image-garden: no curl or wget to fetch http://pkgproxy:3142/setup/$tool" >&2; fi; done; fi
- touch /etc/cloud/cloud-init.disabled| Piece | Runs from | Families | What it leaves in the guest |
|---|---|---|---|
| hosts line | bootcmd and runcmd | all but Ubuntu Core | ADDRESS pkgproxy and a comment in /etc/hosts |
| probe | bootcmd | all but Ubuntu Core | /run/image-garden-pkgproxy-unreachable when pkgproxy does not answer |
/setup/apt | bootcmd | debian, ubuntu | Acquire::http::Proxy in /etc/apt/apt.conf.d/99pkgproxy |
/setup/snap | runcmd | all but alpine and Ubuntu Core | /etc/systemd/system/snapd.service.d/pkgproxy.conf with SNAPPY_FORCE_API_URL; snapd restarted where installed |
GOPROXY | write_files | all but Ubuntu Core | GOPROXY="http://pkgproxy:PORT/go,direct" appended to /etc/environment |
Sources: 010-qemu.mk:127-185, proxy/README.md:166-204.
| Variable | What it is | Override in .image-garden.mk |
|---|---|---|
PKGPROXY_GUEST_URL | http://pkgproxy:PORT | no need |
PKGPROXY_BOOTCMD_SETUP | scripts for bootcmd, called with the group as $1; apt for debian and ubuntu | yes |
PKGPROXY_RUNCMD_SETUP | scripts for runcmd, called with the group; snap for all but alpine | yes |
PKGPROXY_HOSTS_SHELL | the hosts line | not documented |
PKGPROXY_PROBE_SHELL | the probe | not documented |
PKGPROXY_UNREACHABLE_FILE | /run/image-garden-pkgproxy-unreachable | not documented |
PKGPROXY_SETUP_SHELL | the loop that fetches and runs scripts | not documented |
INJECTED_CLOUD_INIT_FILES | the /etc/environment entry | not documented |
All of them are defined only when make found a pkgproxy; otherwise the three blocks are empty (010-qemu.mk:181-185).
Every run fetches the same cloud image, packages, snaps and Go modules again. pkgproxy keeps one copy.
image-garden download-with-… (rulegen.py:480-518); inside the guest, packages, snaps and Go modules come from the distribution's mirrors and the snap store unless pkgproxy is set up (010-qemu.mk:127-185).The first request fetches and keeps a copy; later ones are served from the host's cache. The snap runs a bundled pkgproxy service by default.
image-garden.pkgproxy service: pkgproxy -addr pkgproxy:3142 -socket-path $SNAP_COMMON/pkgproxy.sock -cache-dir $SNAP_COMMON/cache/pkgproxy … (snapcraft.yaml:241).pkgproxy=component (or unset) is the default (configure:11-39).apt, snapd and Go in the guest, and image-garden's own image and checksum downloads on the host, all go through one pkgproxy.
Acquire::http::Proxy), snapd (a reverse relay to the store via SNAPPY_FORCE_API_URL) and Go (a module proxy via GOPROXY) (README.md:38-48)./files/v1/volatile (image-garden:211-269) and for images at /files/v1/fetch?url=…&sha256=…, falling back to the origin (image-garden:281-327).cloud-init adds a pkgproxy hosts entry, runs the apt and snap setup scripts and sets GOPROXY. QEMU's guestfwd or a URL carries the traffic to the host.
PKGPROXY_BOOTCMD_SETUP is apt for Debian and Ubuntu; PKGPROXY_RUNCMD_SETUP is snap for every group but Alpine (010-qemu.mk:129-130); the hosts entry is PKGPROXY_HOSTS_SHELL (010-qemu.mk:134); GOPROXY="…/go,direct" goes into /etc/environment (010-qemu.mk:179).guestfwd sends the guest's 10.0.2.100:3142 to the socket; with a URL, the guest connects to the URL's address (010-qemu.mk:20-44).CI jobs start empty. Keep pkgproxy's cache between jobs, as image-garden-action does, or use a shared pkgproxy, as the GitLab components do.
pkgproxy-url input names a pkgproxy the VM can reach.Next: what pkgproxy adds to user-data, how a guest reaches the host, image downloads, an unreachable pkgproxy, the snap setting and CI caching.
image-garden allocate ubuntu-cloud-24.04.x86_64 starts the machine in the background and prints localhost:PORT.
.run script has no SSH port; the README points to allocate for one that "runs in the background and is available over ssh" (README.md:86-89).image-garden allocate [--spread] [-p PORT] SYSTEM.ARCH [QEMU-OPTION...], plus --premade and --nice (image-garden:995-1039). Arguments after the system name are passed on to the .run script (image-garden:1160).x86-64 in the name is turned into x86_64 (image-garden:1041).flock X.lock image-garden make X.run X.qcow2, unless --premade. A memory warning waits 30 seconds, then allocate goes on.
--premade, allocate runs flock X.lock image-garden make X.run X.qcow2, in .image-garden/ when that directory exists; the comment explains that a file shared by several systems is locked separately, in the download helpers (image-garden:1057-1064).vm.memory_mb from --query, subtracts a reserve (GARDEN_MEMORY_RESERVE, else 2048 MB in a graphical session and 1024 MB otherwise) from MemAvailable, divides by 1.5 and, if the machine needs more, prints a warning and sleeps 30 seconds before continuing (image-garden:711-782).-m; the -snapshot overlay that holds the guest's writes is not counted, wherever it is. The README says so for the snap (README.md:155-161); see living with strict confinement./dev/kvm exists but is not writable (kvm_check, image-garden:670-710).A random free port from 5000 to 9999, or -p PORT. hostfwd=tcp:127.0.0.1:PORT-:22, and -display none.
$XDG_RUNTIME_DIR/image-garden/allocate.lock, taken with flock --exclusive -n in a loop (image-garden:1070-1080). XDG_RUNTIME_DIR falls back to /run, and in the snap to /run/snap.NAME when the directory snapd names does not exist (image-garden:64-72).-p PORT is tried first; otherwise shuf -i 5000-9999 -n 1 until the probe finds it free (image-garden:1088-1102, probe image-garden:798-823).QEMU_DISPLAY_OPTION defaults to -display none and QEMU_NETDEV_USER_EXTRA=",hostfwd=tcp:127.0.0.1:$PORT-:22" (image-garden:1104-1107). Only localhost can reach the port../X.run -snapshot -monitor none -serial file:X.PORT.serial.log -pidfile …/port.PORT.pid -daemonize, with stdout and stderr in X.PORT.*.log.
./X.run ${QEMU_SNAPSHOT_OPTION=-snapshot} -parallel none -monitor none -serial file:X.PORT.serial.log -pidfile $XDG_RUNTIME_DIR/image-garden/port.PORT.pid -daemonize "$@" >X.PORT.stdout.log 2>X.PORT.stderr.log, run in .image-garden/ when it exists (image-garden:1151-1163).4<&-) and released when the script returns (exec 4>&-, image-garden:1163-1164); the system name is saved in port.PORT.system for ps (image-garden:1165-1166).-snapshot, the guest's writes go to a temporary overlay in QEMU's temporary directory, $TMPDIR or else /var/tmp, which is deleted when QEMU exits. In the snap, a wrapper sets TMPDIR to ~/snap/image-garden/common/tmp, on disk, or to the snap's private /tmp when that cannot be made (qemu-var-tmp:6-20).Plain: localhost:PORT. With --spread: wait for the SSH banner, then <ADDRESS localhost:PORT>, or <FATAL …> and exit 213.
--spread, allocate probes the port for an SSH- banner until GARDEN_SSH_WAIT_TIMEOUT (default 600 seconds) runs out, then continues anyway; the comment says spread allows only one minute to connect (image-garden:1167-1202).<FATAL …> and exits 213; if the caller goes away, it discards the machine and exits 1 (image-garden:1175-1196).<ADDRESS localhost:PORT> with --spread, else localhost:PORT (image-garden:1203-1205). A QEMU that fails to start gives <FATAL last stderr line> and exit 213, or "Allocation failed" and exit 1 (image-garden:1208-1218).--spread, allocate still guesses that spread called it from the process tree and prints a warning that this will be removed (image-garden:1113-1148).ssh -p PORT ubuntu@localhost, then image-garden discard localhost:PORT. QEMU_SNAPSHOT_OPTION="" keeps the changes.
--query prints system.users.N.username and .password; for most systems user 0 is root and user 1 the distribution's user, for Ubuntu Core only ubuntu (010-qemu.mk:63-92).discard localhost:PORT kills the PID in port.PORT.pid, removes the pid and system files and a TPM runtime directory; discard -a does it for every machine (image-garden:1221-1274).QEMU_SNAPSHOT_OPTION="" with the script or with allocate (README.md:789-803). The changes then go into X.qcow2, the prepared image itself.Next: spread's adhoc backend, discard and ps, --query, and the serial console.
--spread and discards by the address it was given.Read in the image-garden source at the commit this map describes ("code"). Nothing was run for this page.
| Option | Effect |
|---|---|
--spread | wait for SSH, answer with <ADDRESS …> or <FATAL …> and exit 213 |
-p PORT | use this port if it is free |
--premade | do not run make; the image and launcher must exist |
--nice | run make and QEMU under nice (automatic in an x11 or wayland session) |
SYSTEM.ARCH | the system, such as ubuntu-cloud-24.04.x86_64 |
QEMU-OPTION… | passed on to the .run script, so to QEMU |
Source: image-garden:995-1039.
| Variable | Effect |
|---|---|
QEMU_SNAPSHOT_OPTION | -snapshot unless set; empty keeps the changes |
QEMU_MEM_OPTION, QEMU_SMP_OPTION, … | passed to the .run script |
QEMU_DISPLAY_OPTION | -display none unless set |
GARDEN_SSH_WAIT_TIMEOUT | seconds to wait for SSH with --spread, default 600 |
GARDEN_MEMORY_RESERVE | MB kept for the host in the memory check |
XDG_RUNTIME_DIR | where pid files and the lock go; /run if unset |
| File | Where | What |
|---|---|---|
allocate.lock | $XDG_RUNTIME_DIR/image-garden/ | the port lock, shared by all your machines |
port.PORT.pid | $XDG_RUNTIME_DIR/image-garden/ | QEMU's process ID; discard kills it |
port.PORT.system | $XDG_RUNTIME_DIR/image-garden/ | the system name, for ps |
port.PORT.tpm/ | $XDG_RUNTIME_DIR/image-garden/ | +tpm systems: swtpm's runtime directory |
X.lock | project dir or .image-garden/ | the per-system make lock |
X.PORT.serial.log | project dir or .image-garden/ | the guest console |
X.PORT.stdout.log, X.PORT.stderr.log | project dir or .image-garden/ | QEMU's output |
the -snapshot overlay | $TMPDIR, else /var/tmp; in the snap ~/snap/image-garden/common/tmp | the guest's writes, deleted when QEMU exits; not counted by the memory check |
X is the system name. Sources: image-garden:1057-1068, image-garden:1070-1080, image-garden:1108-1112, image-garden:1151-1166.
The cache keeps downloads for every project; the project directory keeps what was made for it; the runtime directory tracks running machines and is empty after a reboot.
GARDEN_CACHE_DIR, by default $XDG_CACHE_HOME/image-garden or ~/.cache/image-garden; downloads go to GARDEN_DL_DIR, by default $GARDEN_CACHE_DIR/dl (image-garden:20-29).image-garden make builds in .image-garden/ when it exists, else in the current directory (image-garden:982-993).$XDG_RUNTIME_DIR/image-garden; without XDG_RUNTIME_DIR image-garden uses /run (image-garden:61-73). That /run/user/UID is a tmpfs, empty after a reboot, is how systemd-logind sets it up (derived); the man page calls it the "Directory with per-user runtime files that do not persist across reboots" (image-garden.1:529-538).Native or source: ~/.cache/image-garden. Snap: ~/snap/image-garden/common/cache. Container: /var/cache/image-garden, a volume. Downloads are in dl/; GARDEN_CACHE_DIR and GARDEN_DL_DIR override.
SNAP_USER_COMMON set) GARDEN_CACHE_DIR defaults to $SNAP_USER_COMMON/cache; elsewhere to ${XDG_CACHE_HOME:-$HOME/.cache}/image-garden, and with neither HOME nor XDG_CACHE_HOME nor GARDEN_CACHE_DIR the script stops with "set HOME, XDG_CACHE_HOME or GARDEN_CACHE_DIR to say where to keep images" (image-garden:20-29). The makefile sets the same defaults (000-garden.mk:9-12).SNAP_USER_COMMON is ~/snap/image-garden/common for a snap named image-garden (snapd's convention, derived).ENV GARDEN_CACHE_DIR=/var/cache/image-garden and VOLUME /var/cache/image-garden (Dockerfile:96-97); the README mounts $HOME/.cache/image-garden there (README.md:365-382). Without a mount, docker gives the volume a new anonymous volume per container (derived).$SNAP_COMMON/cache/pkgproxy, apart from this one; see why pkgproxy.GARDEN_CACHE_DIR and GARDEN_DL_DIR are read from the environment by both the script and the makefile; a moved GARDEN_DL_DIR leaves existing overlays pointing at the old place, see rebase.dl/ubuntu/ holds the image, its .sha256sums, an empty .lock, ubuntu-cloud-24.04.x86_64.url and .filename, and the link ubuntu-cloud-24.04.x86_64.qcow2 that prepared disks use as their backing file.
$(GARDEN_DL_DIR)/GROUP (rulegen.py:447-450); X.url, X.filename and the link X.qcow2 are written there (rulegen.py:480-536).FILE, FILE.sha256sums (or .sha512sums) and FILE.lock in the same directory (image-garden:351-356, image-garden:475-545). During a download there may also be FILE.partial or FILE.sha256sums.partial; see download and verify..img.xz download and the converted .qcow2 there (010-qemu.mk:334-347).# WARNING: The .qcow2 file refers to a file in DL/GROUP (from image-garden make -n).allocate adds SYSTEM.lock and, per machine, SYSTEM.PORT.serial.log, .stdout.log and .stderr.log. discard keeps the logs; make clean removes every *.log.
--premade, allocate runs flock <.image-garden/ or ./>SYSTEM.lock image-garden make SYSTEM.run SYSTEM.qcow2 (image-garden:1058-1064).-serial file:SYSTEM.PORT.serial.log and redirects standard output and error to SYSTEM.PORT.stdout.log and SYSTEM.PORT.stderr.log, in .image-garden/ when it exists (image-garden:1153-1163). With --spread, a failed start prints the last line of the stderr log in <FATAL …>.discard kills the process and removes the pid and system files and a TPM run directory, not the logs (image-garden:1221-1274).make clean runs rm -f *.log in the directory make runs in (000-garden.mk:48-50). The lock files are not removed by any rule.SYSTEM.x86_64.tpm/ next to the disk (README.md:836-837); make clean removes it (050-ubuntu-core.mk:315-319).$XDG_RUNTIME_DIR/image-garden/ holds allocate.lock, port.PORT.pid, port.PORT.system, port.PORT.tpm/ and pkgproxy-unreachable.HASH. Without XDG_RUNTIME_DIR it is /run/image-garden/.
XDG_RUNTIME_DIR falls back to /run, "in CI/CD systems that run a container runtime and don't use systemd or its PAM module"; in the snap, when the directory snapd names does not exist, image-garden uses /run/snap.$SNAP_INSTANCE_NAME (image-garden:61-73); see the snap's paths.allocate.lock is taken with flock --exclusive -n in a loop while allocate picks a port and starts QEMU (image-garden:1070-1080).port.PORT.pid through -pidfile; allocate writes the system's name to port.PORT.system (image-garden:1153-1166); ps and discard read them (image-garden:1221-1358).port.PORT.tpm holds swtpm's socket and, as the machine runs with -snapshot, its copy of the TPM state (image-garden:825-831). The first boot of a +tpm system runs swtpm in a tpm.XXXX directory there (050-ubuntu-core.mk:84-89).pkgproxy-unreachable.HASH, with the first 16 hex digits of the sha256 of the pkgproxy address, is touched when curl cannot resolve, connect or connect in time; downloads skip that pkgproxy while the file is younger than 300 seconds; sockets are not remembered (image-garden:138-193).make clean empties the project and removes the cache links; distclean also removes the downloads with their .url and .filename files. Either way of emptying the cache costs a download and a provisioning boot per system.
clean:: rules remove *.log (000-garden.mk:48-50); *.seed.iso, *.meta-data, *.user-data (010-qemu.mk:300-302); the firmware copies and *.x86_64.qcow2 with the per-system firmware files (010-qemu-x86_64.mk:332-334, and the same for the other architectures); and per system the cache link $(GARDEN_DL_DIR)/GROUP/X.qcow2, X.qcow2, X.run, X.meta-data and X.user-data (rulegen.py:473-478).distclean:: clean comes first in image-garden.mk (000-garden.mk:52-53). Each system's distclean:: recipe then removes the file the link points to, if the link is still there, and the file named in X.filename, which clean keeps, then the link, X.url and X.filename (rulegen.py:486-492). The README: distclean "also removes downloaded base images from the cache directory" (README.md:547-550).distclean:: removes ubuntu-core-R-*.img.xz and the converted ubuntu-core-R-*.qcow2 from $(GARDEN_DL_DIR)/ubuntu-core/ (050-ubuntu-core.mk:326-328), where they are downloaded (050-ubuntu-core.mk:229-232).image-garden.mk built from the commit in garden.commit: image-garden make distclean removed the project files, the image of ubuntu-cloud-24.04.x86_64 with its link, .url and .filename, and Ubuntu Core's .img.xz and converted .qcow2.distclean in one project also takes the backing files of the prepared disks of the others (derived)..lock files in the cache are removed by no rule; deleting the cache directory by hand removes everything. A prepared disk whose backing file is gone fails to boot from .run; image-garden make sees the missing link, downloads the image again, and the newer image makes it provision the disk again (derived from the rules). After distclean the disks are gone as well, so make provisions them in any case.make distclean)" (README.md:860-868).ps and discard cannot see it (derived); image-garden ps --stale lists entries whose QEMU is gone.Next: download and verify, rebase, discard and ps, the snap's paths and the container.
Read in the image-garden source at the commit in garden.commit ("code"): the image-garden script, mk/*.mk, rulegen.py, the Dockerfile and the README. What make clean and make distclean leave behind was checked by running them with an image-garden.mk built from that tree on a scratch cache ("run"). The snap's SNAP_USER_COMMON path and the lifetime of /run/user/UID follow from how snapd and systemd set them up ("derived").
| Place | Default | Holds | Lifetime |
|---|---|---|---|
cache (GARDEN_CACHE_DIR) | see the next table | downloads in dl/, shared by every project of the user | until you delete it |
| project | the current directory, or .image-garden/ when it exists | disks, launchers, seeds, firmware copies, logs, allocate's locks | until make clean |
runtime ($XDG_RUNTIME_DIR/image-garden) | /run/user/UID/image-garden, or /run/image-garden without XDG_RUNTIME_DIR | allocate's lock, pid and system files, TPM run directories, pkgproxy-unreachable markers | until reboot |
| Install | GARDEN_CACHE_DIR | Downloads (GARDEN_DL_DIR) |
|---|---|---|
| native package or source | ${XDG_CACHE_HOME:-~/.cache}/image-garden | ~/.cache/image-garden/dl |
| snap | $SNAP_USER_COMMON/cache | ~/snap/image-garden/common/cache/dl |
| container | /var/cache/image-garden (a volume) | /var/cache/image-garden/dl |
Either variable may be set in the environment to move the cache or only the downloads (image-garden:20-29, 000-garden.mk:9-12, Dockerfile:96-97). The snap's pkgproxy has a cache of its own in $SNAP_COMMON/cache/pkgproxy.
In dl/GROUP/, for a system X whose download is FILE:
| File | Made by | Removed by |
|---|---|---|
FILE | the download helper | distclean |
FILE.sha256sums or FILE.sha512sums | the download helper | a failed check |
FILE.lock | the download helper | nothing |
FILE.partial, FILE.sha256sums.partial | an unfinished download | a completed download |
X.url, X.filename | make | distclean |
X.qcow2, a link to FILE | make | clean, distclean |
| File | Made by | Removed by |
|---|---|---|
X.qcow2, X.qcow2.log, X.run, X.seed.iso, X.user-data, X.meta-data | make | clean |
X.efi-code.qcow2, X.efi-vars.qcow2, efi-code.ARCH.img, efi-vars.ARCH.img | make | clean |
X.x86_64.tpm/ (+tpm systems) | the first boot | clean |
X.lock | allocate | nothing |
X.PORT.serial.log, X.PORT.stdout.log, X.PORT.stderr.log | allocate | clean (any *.log) |
| File | Made by | Removed by |
|---|---|---|
allocate.lock | allocate | nothing; it is only locked |
port.PORT.pid | QEMU's -pidfile | discard, a failed allocate |
port.PORT.system | allocate | discard |
port.PORT.tpm/ | the launcher of a +tpm system | its watcher, discard |
tpm.XXXX/ | the first boot of a +tpm system | that boot |
pkgproxy-unreachable.HASH | a download that cannot reach pkgproxy | nothing; it is ignored after 300 seconds |
Sources: image-garden:138-193, image-garden:825-859, image-garden:1070-1274, 050-ubuntu-core.mk:84-106.
| Command | Removes | Keeps |
|---|---|---|
image-garden make clean | in the project: every file in the project table but the locks; in the cache: the system links | the downloads, their lists and locks, .url, .filename |
image-garden make distclean | what clean removes, then each system's download (found through X.filename), .url and .filename, and Ubuntu Core's .img.xz and converted .qcow2 | the checksum lists and locks |
distclean works as the README says (README.md:547-550, rulegen.py:486-492, 050-ubuntu-core.mk:326-328). The downloads are shared by every project, so other projects' prepared disks lose their base too; the next make there downloads what it needs and provisions the disks again (derived).
make works back from ubuntu-cloud-24.04.x86_64.run to the image URL, then builds forwards: ten files, each made only when it is missing or older than what it is made from.
X.run depends on the makefiles and, order-only, on X.qcow2, X.efi-code.qcow2 and X.efi-vars.qcow2 (rulegen.py:593-599).X.qcow2 depends on the download link $(GARDEN_DL_DIR)/ubuntu/X.qcow2, X.seed.iso and the two firmware copies (rulegen.py:601-602).X.user-data and X.meta-data (010-qemu.mk:268-278); the download link on X.url and X.filename (rulegen.py:511-514); the firmware copies on efi-code.x86_64.img and efi-vars.x86_64.img (010-qemu-x86_64.mk:316-329).image-garden make -n prints them, in the reference below.In ~/.cache/image-garden/dl/ubuntu/: .url, .filename, the verified image, and the link ubuntu-cloud-24.04.x86_64.qcow2 that every later step uses.
$(GARDEN_DL_DIR)/ubuntu is made with mkdir -p (rulegen.py:447-450).X.url, depends on the makefiles and holds the URL key, written out with echo, or the output of URLProgram (rulegen.py:520-530).X.filename, holds LocalFilename when the section sets it, otherwise the URL's last path component; for a URLProgram system it is worked out from the .url file, with URLPattern and LocalFilenameTemplate when they are set (rulegen.py:532-591, rulegen.py:782-799).image-garden download-with-sha256sums $(cat X.url) <SHA256SUMS URL> $(GARDEN_DL_DIR)/ubuntu $(cat X.filename); step 4 makes the link with GARDEN_SYMLINK, ln -sfn to a temporary name and one mv -fT, so that two makes can make it at once (rulegen.py:510-514, 000-garden.mk:58-64). Steps 3 and 4 are one recipe.URL (ubuntu.ini:237-242). The path on the slide is the default cache of a native or source install; see where files live.X.url depends on the makefiles, an upgrade or an edit of .image-garden.mk rewrites it; the cached image is then older than X.url, so the download recipe runs on every later make and checks the image again without fetching it.Steps 5 to 8: .user-data and .meta-data, the cidata seed ISO, efi-code.x86_64.img and efi-vars.x86_64.img copied once, and the system's own .efi-code.qcow2 and .efi-vars.qcow2.
image-garden make runs make with -C .image-garden when that directory exists, else in the current directory (image-garden:982-993).X.meta-data and X.user-data are written from the templates; both depend on the makefiles, and the user-data also on the project's .image-garden.mk (rulegen.py:460-471). make -n prints the user-data first.%.seed.iso is made by xorriso -as genisoimage … -volid cidata with the two files grafted in as user-data and meta-data (010-qemu.mk:263-278).efi-code.x86_64.img and efi-vars.x86_64.img are copied with cp --preserve=timestamps from the first file found in a search list of host paths, then the snap's QEMU component, then GARDEN_X86_64_PREFIX (010-qemu-x86_64.mk:260-280, 010-qemu-x86_64.mk:316-322). When none is found make warns "please install x86_64 edk2 firmware".%.x86_64.efi-code.qcow2 and %.x86_64.efi-vars.qcow2 are made with qemu-img convert -f raw -O qcow2 (010-qemu-x86_64.mk:324-329). The code is attached read-only as pflash unit 0 and the variables writable as unit 1 (010-qemu-x86_64.mk:21-22).ubuntu-cloud-24.04.x86_64.run lists the disk and firmware after a |: they must exist, but a newer disk does not rewrite the launcher. The makefiles, .image-garden.mk included, do.
X.run: $(MAKEFILE_LIST) | $(if $(GARDEN_RUN_REQUIRES_QCOW2),X.qcow2) X.efi-code.qcow2 X.efi-vars.qcow2; the disk rule creates the overlay and runs the provisioning boot in one recipe (rulegen.py:593-610). Prerequisites after | are order-only in GNU make: they are made first if missing, but their time stamps do not make the target out of date.GARDEN_RUN_REQUIRES_QCOW2 ?= 1 (010-qemu.mk:14); set it empty and make X.run writes the launcher without making the disk.$(MAKEFILE_LIST) includes the project's .image-garden.mk, which mk/999-local.mk includes before the generated rules are read (999-local.mk:4-5).make -n: with every file present, X.run is up to date; with a newer X.qcow2, still up to date; with X.run deleted, only "Generate launcher script" is printed.ruleset_x86_64_efi; the BIOS, aarch64, riscv64, loongarch64, s390x and ppc64 templates use the same order-only pattern (rulegen.py:593-724)..DELETE_ON_ERROR removes a target whose recipe failed. A failed provisioning boot leaves no .qcow2 but keeps .qcow2.log; the next make starts again at step 9.
mk/000-garden.mk starts with .DELETE_ON_ERROR:, "so that a partially built file, like firmware that was copied but not resized, is not considered up to date on the next invocation" (000-garden.mk:4-7). It comes first in image-garden.mk, after the list of systems.set -o pipefail && <QEMU command> 2>&1 | tee X.qcow2.log, so a QEMU failure fails the recipe; the log is not a target and stays (rulegen.py:605-609)..DELETE_ON_ERROR and .PRECIOUS: %.qcow2 %.img, a failing explicit x.qcow2 rule still deletes x.qcow2, because a pattern in .PRECIOUS covers files made by pattern rules, not explicit targets. make also deletes a target it was making when you press Control C..PRECIOUS: "Another make may download the same image, and make the same link, at the same time: a make that is interrupted must not remove it" (rulegen.py:494-496).FILE.partial, which it keeps on failure or interrupt so that the next run resumes (image-garden:528-537).image-garden make -n on a finished system: up to date. Without the seed: seed, overlay, provisioning. Without the launcher: the launcher alone.
-n prints the commands without running them (README.md:514-519).image-garden script and an image-garden.mk built from the v0.8.0 tree, whose rules for these files are the same at the commit in garden.commit, on a scratch project whose files were created in build order. The output on the slide is abridged: -n also prints the printf lines of the banners and every line of the launcher.X.qcow2: … X.seed.iso …), so a new seed means a new overlay and a new provisioning boot (rulegen.py:601-609); the launcher has the disk only as an order-only prerequisite (rulegen.py:594-594).Next: downloads, the overlay, the first boot and where files live.
Next: downloads, the overlay, the first boot, where files live and how rulegen.py writes the rules.
The rules were read in the image-garden source at the commit in garden.commit ("code"). The order of the steps and the three dry runs were produced by running image-garden make -n with the image-garden script and an image-garden.mk built from the v0.8.0 tree, whose rules for these steps are the same, in a scratch project with a fake cache ("run"). What GNU make does with .DELETE_ON_ERROR, .PRECIOUS and order-only prerequisites was checked on small makefiles with GNU make 4.4.1 ("derived").
For image-garden make ubuntu-cloud-24.04.x86_64.run, with X the system name and DL the download cache (~/.cache/image-garden/dl for a native or source install). Files 5 to 10 are made in the project directory, or in .image-garden/ when it exists.
| Step | File | Made by | Made again when |
|---|---|---|---|
| 1 | DL/ubuntu/X.url | echo of the URL key, or the URLProgram output | the makefiles change |
| 2 | DL/ubuntu/X.filename | LocalFilename, or the URL's last component | the makefiles change (or X.url, for URLProgram systems) |
| 3 | DL/ubuntu/noble-server-cloudimg-amd64.img | image-garden download-with-sha256sums | missing, or failing its check |
| 4 | DL/ubuntu/X.qcow2, a link to step 3 | ln -sfn and mv -fT | X.url or X.filename is newer than the image |
| 5 | X.user-data, X.meta-data | the cloud-init templates | the makefiles, or .image-garden.mk, change |
| 6 | X.seed.iso | xorriso -as genisoimage -volid cidata | step 5 is remade |
| 7 | efi-code.x86_64.img, efi-vars.x86_64.img | cp from the EDK2 firmware | the source firmware is newer |
| 8 | X.efi-code.qcow2, X.efi-vars.qcow2 | qemu-img convert | step 7 is remade |
| 9 | X.qcow2 and X.qcow2.log | qemu-img create -b on step 4, then the provisioning boot | steps 4, 6 or 8 are newer |
| 10 | X.run | the launcher macro | the makefiles change, or it is missing |
image-garden make clean removes steps 4 to 10 (the link in step 4 included); image-garden make distclean also removes steps 1 to 3, the download with its .url and .filename (rulegen.py:473-492). See where image-garden keeps its files.
Sources: rulegen.py:447-610, 010-qemu.mk:263-278, 010-qemu-x86_64.mk:316-329.
"The makefiles" is $(MAKEFILE_LIST): image-garden.mk and the project's .image-garden.mk. make compares the time of the link in step 4 by following it to the image, so after the makefiles change, step 4 runs on every make (the helper checks the image again but does not fetch it) until the image itself is downloaded again (run).
| Banner | Step |
|---|---|
| Resolve URL for X | 1 |
| Resolve local filename for X | 2 |
| Download and verify base image for X | 3 and 4 |
| Generate cloud-init user-data for X, Generate cloud-init meta-data for X | 5 |
| Create cloud-init seed ISO X.seed.iso | 6 |
| Prepare writable qcow2 for X | 9, the overlay |
| Provision X | 9, the boot |
| Generate launcher script for X | 10 |
The section banners, framed with =, are cut to 44 characters; the other titles are underlined with dashes (000-garden.mk:32-41).
Boot=bios) have no steps 7 and 8; s390x and ppc64 systems neither.efi-code.ARCH.img and so on)..img.xz and converts it to qcow2 in the cache before the link is made; see Ubuntu Core.BASE@NAME.ARCH has its own steps 5, 6, 8, 9 and 10 on the base system's link; see named instances.| Target | Where | Effect |
|---|---|---|
.DELETE_ON_ERROR: | 000-garden.mk:7 | a target whose recipe fails is deleted |
.PRECIOUS: DL/GROUP/X.qcow2 | rulegen.py:494-496 | the cache link is kept when make is interrupted |
.PRECIOUS: %.qcow2 %.img | 010-qemu.mk:334 | files made by the convert pattern rules are kept; the explicit X.qcow2 overlay is not covered (derived) |
X.run with the disk after the bar | rulegen.py:594-594 | the disk and firmware are order-only prerequisites of the launcher |
The default display option is -nographic: the guest's serial console is your terminal.
QEMU_DEFAULT_DISPLAY_OPTION ?= -nographic (010-qemu.mk:13); the script uses it unless QEMU_DISPLAY_OPTION is set (010-qemu-x86_64.mk:66, 010-qemu-x86_64.mk:99).-nographic, QEMU has no graphical output and connects the first serial port to standard input and output. Derived: this is how QEMU's -nographic mode and a serial line behave in general; image-garden's source sets the option but does not describe the behaviour.Ctrl-A H help, Ctrl-A C monitor and back, Ctrl-A X quit QEMU, Ctrl-A Ctrl-A sends one Ctrl-A to the guest.
-nographic mode and a serial line behave in general; image-garden's source sets the option but does not describe the behaviour. Under -nographic, QEMU multiplexes the serial port and its monitor on the terminal; Ctrl-A is the escape key, Ctrl-A H prints the keys, Ctrl-A C switches between the console and the monitor, Ctrl-A X exits QEMU, Ctrl-A Ctrl-A sends one Ctrl-A.Ctrl-A is also the shell's "start of line" key and screen's or tmux's prefix in many setups; inside the guest, press it twice.-monitor none and sends the serial port to a file (image-garden:1155-1157).Ctrl-C reaches the guest, not QEMU. Shut down from inside; Ctrl-A X stops QEMU at once, like pulling the plug.
-nographic mode and a serial line behave in general; image-garden's source sets the option but does not describe the behaviour. In -nographic mode the terminal is raw, so Ctrl-C is sent to the guest as a character.Ctrl-A X ends QEMU at once; without -snapshot, writes the guest had not flushed are lost and the image keeps whatever reached it (README.md:85-86 for the persistent default; the rest derived).Run stty size on the host, then stty rows R cols C in the guest, or resize where it is installed.
-nographic mode and a serial line behave in general; image-garden's source sets the option but does not describe the behaviour. A serial line has no way to send the window size, so the guest keeps its default, commonly 80 by 24, until told otherwise.stty size prints rows then columns; stty rows R cols C sets them for the guest's terminal. resize comes with xterm and may not be installed in a cloud image.Kernel messages share the console. The provisioning boot's console is in X.qcow2.log; an allocated machine's in X.PORT.serial.log.
-nographic mode and a serial line behave in general; image-garden's source sets the option but does not describe the behaviour. The kernel writes its messages to the console it was given, whatever is being typed there.tee X.qcow2.log (rulegen.py:604-609).-serial file:X.PORT.serial.log (image-garden:1153-1163), so an allocated machine's console goes to that file.For long work use image-garden allocate and SSH. For a window, QEMU_DISPLAY_OPTION="-display gtk".
QEMU_DISPLAY_OPTION to -display none unless you set it, and forwards a local port to the guest's SSH port (image-garden:1105-1107).-display gtk for a graphical display (README.md:928-929).Next: image-garden allocate, the .run script's variables, and the provisioning boot.
.run scripts started by hand; allocate starts them with no display, no monitor and the console in a file.The default display option was read in the image-garden source at the commit in garden.commit ("code"). The keys and terminal behaviour are QEMU's and a serial line's general behaviour ("derived"); image-garden does not change them.
| Where | Press or type | What happens |
|---|---|---|
| console | Ctrl-A H | QEMU lists its keys |
| console | Ctrl-A C | switch to the QEMU monitor; again to switch back |
| console | Ctrl-A X | QEMU exits at once, like pulling the plug |
| console | Ctrl-A Ctrl-A | one Ctrl-A reaches the guest |
| console | Ctrl-C | interrupts the program in the guest, not QEMU |
| console | Ctrl-U, Enter | clear a line broken up by a message, or get a fresh prompt |
| host | stty size | prints your terminal's rows and columns |
| guest | stty rows R cols C | tells the guest the size |
| guest | resize | works out the size itself, where installed |
| guest | sudo shutdown -h now | a clean end: the guest powers off and QEMU exits |
| host | QEMU_DISPLAY_OPTION="-display gtk" ./X.run | a window instead of the serial console |
| host | image-garden allocate X then ssh -p PORT user@localhost | a normal terminal over SSH |
| How the machine was started | Console |
|---|---|
./X.run | your terminal (-nographic, 010-qemu.mk:13) |
| provisioning boot by make | your terminal and X.qcow2.log (rulegen.py:604-609) |
image-garden allocate | X.PORT.serial.log, no monitor (image-garden:1155-1157) |
allocate leaves port.5555.pid and port.5555.system in $XDG_RUNTIME_DIR/image-garden/. discard and ps read nothing else.
-pidfile $XDG_RUNTIME_DIR/image-garden/port.PORT.pid to the .run script, so QEMU writes its own PID there, then saves the system name in port.PORT.system "for ps command" (image-garden:1153-1166).XDG_RUNTIME_DIR falls back to /run, and in the snap to /run/snap.NAME when snapd's directory does not exist (image-garden:61-73). discard and ps must see the same value as the allocate that started the machine.image-garden discard localhost:5555 kills the PID, removes port.5555.pid, port.5555.system and port.5555.tpm/. The logs stay. Any other address form exits 1 silently.
localhost:PORT it reads port.PORT.pid, runs kill PID || true (SIGTERM, the default signal), removes port.PORT.pid and port.PORT.system and calls discard_tpm_run_dir; when the pid file is missing it does nothing and exits 0. Any other address form exits 1 without a message (image-garden:1254-1272). Run: discard 127.0.0.1:5555 exited 1 and printed nothing..image-garden/, are not touched (image-garden:1157-1162).-snapshot unless QEMU_SNAPSHOT_OPTION was set, so stopping it drops every change made in the guest (image-garden:1154).exec image-garden discard "$SPREAD_SYSTEM_ADDRESS", as the README does, so discard's exit status is the hook's (spread.yaml:48-59); the craft components discard from an exit trap (snapcraft-vm:268-281).image-garden discard -a discards the machine of every port.*.pid in the runtime directory, from every project, and exits 0.
discard -a exits 0 when $XDG_RUNTIME_DIR/image-garden does not exist; otherwise, for each port.*.pid in glob order, it kills the PID, removes the pid and system files and the TPM directory, and exits 0 (image-garden:1223-1247).-a reaches every machine your user allocated (derived from image-garden:61-73). Where XDG_RUNTIME_DIR is unset and falls back to /run, as in many CI containers, every user of that /run shares it.localhost:PORT it finds in restore-each (spread.yaml:81-90).image-garden ps prints ADDRESS, PID, RSS(MB) and SYSTEM for each pid file whose process runs. RSS comes from /proc/PID/status.
ADDRESS PID RSS(MB) SYSTEM with printf '%-16s %-8s %-8s %s', and exits 0 with only the header when the runtime directory does not exist (image-garden:1300-1307).port.*.pid whose PID runs: /proc/PID exists, or kill -0 succeeds (image-garden:1309-1356, image-garden:867-878).VmRSS from /proc/PID/status, divided by 1024, one decimal (image-garden:880-885). The system name comes from port.PORT.system, or - without one (image-garden:1347-1350).-m, is derived from how Linux counts resident memory.image-garden ps [--all] [--stale]; any other option gives "image-garden: unknown option" and exit 1 (image-garden:1276-1299).ps --stale lists entries whose process is gone, or whose pid file is malformed; ps --all lists everything. discard removes a stale entry.
(stale) when its PID is a number that does not run, (malformed) when the pid file does not hold a number. Default: running entries only; --stale: stale and malformed ones only; --all: every entry, with the suffix (image-garden:1309-1355).ps showed one row, ps --all both with (stale) on the dead one and an empty RSS column, ps --stale only the dead one.kill (image-garden:1260-1265). PID reuse is derived from how Linux assigns process IDs.For port.5555.tpm/, discard waits up to 5 s for swtpm to exit, kills it, and removes the directory, retrying for 2 s while the launcher's watcher does the same.
$XDG_RUNTIME_DIR/image-garden/port.PORT.tpm, exports it as GARDEN_TPM_RUN_DIR and removes a leftover one first (image-garden:825-831, image-garden:1108-1112).discard_tpm_run_dir reads swtpm.pid, waits up to 50 × 0.1 s while swtpm runs and is not a zombie, then kills it; then it tries rm -rf up to 20 times, 0.1 s apart, and a last time that may fail (image-garden:833-865).tail --pid=… -f /dev/null; rm -rf …, removes the directory when swtpm exits (010-qemu-x86_64.mk:203).+tpm Ubuntu Core systems have such a directory.Next: allocate, spread's adhoc backend, swtpm per launch, and where image-garden keeps its files.
Read in the image-garden source at the commit in garden.commit ("code"). The outputs of ps, ps --all, ps --stale and discard were run with the v0.8.0 script, whose ps and discard are unchanged at that commit, against a scratch XDG_RUNTIME_DIR holding one pid file of a live process and one of a dead one; no VM was started. PIDs, ports and RSS values on the slides are examples.
| Command | Effect | Exit | |
|---|---|---|---|
image-garden discard localhost:PORT | kill the PID in port.PORT.pid, remove it, port.PORT.system and port.PORT.tpm/ | 0, also when there is no pid file | |
image-garden discard -a | the same for every port.*.pid | 0 | |
image-garden discard | prints "usage: image-garden discard ADDRESS \ | -a" | 1 |
image-garden discard OTHER | nothing | 1 | |
image-garden ps | header and running entries | 0 | |
image-garden ps --stale | header and stale or malformed entries | 0 | |
image-garden ps --all | header and every entry, with (stale) or (malformed) | 0 |
Sources: image-garden:1221-1358.
File in $XDG_RUNTIME_DIR/image-garden/ | Written by | Removed by |
|---|---|---|
port.PORT.pid | QEMU (-pidfile) | discard, allocate when the machine fails to come up |
port.PORT.system | allocate | discard, allocate when the machine dies before SSH |
port.PORT.tpm/ | the +tpm launcher | the launcher's watcher, discard, the next allocate on that port |
allocate.lock | allocate | nothing; it is a lock |
Sources: image-garden:1070-1080, image-garden:1108-1112, image-garden:1151-1215, 010-qemu-x86_64.mk:173-203.
$ image-garden ps --all ADDRESS PID RSS(MB) SYSTEM localhost:5555 41872 812.6 ubuntu-cloud-24.04.x86_64 localhost:7021 38110 fedora-cloud-42.x86_64 (stale)
The download step runs image-garden download-with-sha256sums URL SUMS-URL DIR FILE, which copes with broken transfers, stale lists, interrupts and concurrent makes.
SHA256SUMS system runs $(GARDEN_ITSELF) download-with-sha256sums $(cat X.url) <SHA256SUMS> $(GARDEN_DL_DIR)/<group> $(cat X.filename) (rulegen.py:510-514); GARDEN_ITSELF is the image-garden script that started make (image-garden:982-993).download-with-sha512sums, download-with-sha256sums, download-with-sha256sum and download (no checksum, not used by the generated rules) (image-garden:358-668). The checksum list defaults to SHA256SUMS next to the image, the directory to $GARDEN_DL_DIR and the file name to the URL's last component (image-garden:460-473).image-garden --help brackets the optional arguments, download-with-sha256sums URL [SHA256SUMS_URL [DIRECTORY_PREFIX [FILENAME]]], and says what they default to; only download-with-sha256sum needs its checksum (image-garden:898-904, image-garden:562-577). The man page agrees (image-garden.1:24-27).[ubuntu-cloud-24.04.x86_64] (ubuntu.ini:237-242) with the cache of a native or source install.CI set, curl runs without its progress meter (image-garden:107-119).Ubuntu's and Debian's images are checked against a published list of SHA-256 or SHA-512 hashes; Oracle's against a hash image-garden carries itself. Lists may be GNU style, BSD style or one bare hash.
download-with-sha512sums when SHA512SUMS is set, else download-with-sha256sum when SHA256SUM is set, else download-with-sha256sums (rulegen.py:498-517). A section without any of the three is refused when the rules are generated (rulegen.py:426-431).SHA512SUMS, Oracle Linux (7) uses SHA256SUM, every other file SHA256SUMS. Fedora's SHA256SUMS points at its CHECKSUM file, openSUSE's at a .sha256 file; @URL@ in the value stands for the image URL (rulegen.py:82-88).find_checksum_hash accepts HASH NAME or HASH *NAME lines, BSD lines KIND (NAME) = HASH, and a file whose only non-empty line is a bare hash of the right length (image-garden:75-92).SHA256SUMS is saved as noble-server-cloudimg-amd64.img.sha256sums; the image arrives as .partial, through pkgproxy by hash or from the origin, is renamed when complete, then checked.
DIR/FILE.sha256sums does not exist, to FILE.sha256sums.partial, and renamed when complete (image-garden:480-506). The hash is taken from it before the image is fetched, "so that the download can go through a pkgproxy" (image-garden:508-515).GARDEN_DL_PKGPROXY, by default PKGPROXY_URL or the snap's), the list is asked from /files/v1/volatile?url=… (image-garden:211-269) and the image from /files/v1/fetch?url=…&sha256=HASH, one try with a 10 second connect timeout, then from the URL directly (image-garden:281-308). The details are in image downloads through pkgproxy.DIR/FILE does not exist, into FILE.partial, then mv -v to FILE (image-garden:517-540).printf '%s %s\n' HASH FILE | sha256sum --check, run in DIR (image-garden:542-545). It also runs when the image was already there.curl exit 18 (short response) or 56 (broken connection) is resumed with --continue-at -, up to five times. After Control C the image's .partial stays for the next run; a partial list is removed.
curl --fail --location --retry 5 --retry-connrefused --continue-at - (image-garden:310-327, image-garden:107-119). It prints "Download of URL ended short, resuming".FILE.interrupted; the helper then removes that marker and returns 1. For the image, "Leave the partial file around, on interrupt or failure, so that we can resume the download later"; for the list, "Remove the partial file, on interrupt or failure, as it is our only protection against corruptions of the main content and the checksum files are small" (image-garden:480-540)..partial with --continue-at -, so the direct download that follows resumes what came through pkgproxy (image-garden:290-298).--retry 3 (image-garden:269-269).download helper, which has no checksum, deletes its partial file on interrupt (image-garden:655-660).On FAILED both the image and .sha256sums are removed and the download runs once more from the list; a second failure stops make. Only the .lock file is left.
for attempt in first retry. When the hash is empty or sha256sum --check fails, it runs rm -vf FILE FILE.sha256sums, "so that we re-download the checksum file. This can help if we have a stale checksum from the past that will never match the current download", continues on the first attempt and returns 1 on the second (image-garden:542-559). The SHA512 helper does the same (image-garden:440-457); the single-hash helper removes only the image (image-garden:613-623).file:// origin whose list held a wrong hash, with CI set; paths are shortened, and the rm -v lines are shown as an English locale prints them. After both attempts only FILE.lock was left in the directory.Each helper holds flock on FILE.lock across fetch, check and retry. The link is replaced with one mv; allocate locks SYSTEM.lock around its make.
GARDEN_SYMLINK replaces the link with one rename, because "of two at once, one may find the other's link and fail, as uutils ln, the default ln in Ubuntu 26.04, does" (000-garden.mk:58-64); the link is .PRECIOUS (rulegen.py:494-496).ubuntu-core-24-amd64.img.xz; its conversion to qcow2 in the cache runs under a lock of its own (010-qemu.mk:304-347); see Ubuntu Core.allocate runs flock <.image-garden/ or ./>SYSTEM.lock image-garden make SYSTEM.run SYSTEM.qcow2 unless --premade (image-garden:1058-1064).Next: image downloads through pkgproxy, checksums for contributors, where files live and the overlay.
The helpers were read in the image-garden script at the commit in garden.commit ("code"). The mismatch output was produced by running image-garden download-with-sha256sums from the v0.8.0 tree, whose helpers are the same, against a local file:// origin ("run"). Statements about formats published by distributions are marked "derived".
| Command | Checksum | Used by |
|---|---|---|
image-garden download-with-sha512sums URL [SUMS-URL] [DIR] [FILENAME] | a SHA512SUMS list, by default SHA512SUMS next to URL | sections with SHA512SUMS (Debian, Alpine) |
image-garden download-with-sha256sums URL [SUMS-URL] [DIR] [FILENAME] | a SHA256SUMS list, by default SHA256SUMS next to URL | sections with SHA256SUMS (most), Ubuntu Core |
image-garden download-with-sha256sum URL SHA256 [DIR] [FILENAME] | one known hash | sections with SHA256SUM (Oracle Linux) |
image-garden download URL [DIR] [FILENAME] | none | no generated rule |
DIR defaults to $GARDEN_DL_DIR, FILENAME to the URL's last component (image-garden:358-668); image-garden --help shows the same brackets and defaults (image-garden:898-904). The generated rules always pass all four arguments.
For FILE noble-server-cloudimg-amd64.img:
| File | Lifetime |
|---|---|
FILE.lock | made by the first download, empty, left in place |
FILE.sha256sums.partial | while the list downloads; deleted on failure or interrupt |
FILE.sha256sums | the saved list; deleted with the image on a failed check |
FILE.partial | while the image downloads; kept on failure or interrupt, resumed next time |
FILE.interrupted | marker made by the Control C trap, removed at once |
FILE | the verified image |
1. Lock FILE.lock with flock. 2. Print the banner "Download and verify image: FILE (sha256sums)". 3. If FILE.sha256sums is missing: fetch the list through pkgproxy's volatile files, else from SUMS-URL with --retry 3, into .partial, then rename. 4. Find the hash of FILE in the list, else of the URL's basename. 5. If FILE is missing: fetch it through pkgproxy by hash, else from URL, into FILE.partial, resuming on curl exit 18 or 56 up to five times; rename. 6. Check the hash with sha256sum --check. On success, return. 7. On failure: remove FILE and FILE.sha256sums; on the first attempt go back to step 3, on the second fail.
Sources: image-garden:460-560, image-garden:211-327.
| Message | Meaning |
|---|---|
Downloading through pkgproxy at ADDRESS | the list or the image is asked from pkgproxy first |
Cannot download through pkgproxy, downloading URL directly | pkgproxy failed; the origin is used |
Download of URL ended short, resuming | curl exit 18 or 56; the download continues |
FILE: FAILED | the hash does not match; both files are removed |
Cannot find checksum entry for NAME in LIST | the list has no line for the file; both files are removed |
The pkgproxy messages are explained in image downloads through pkgproxy and when pkgproxy is unreachable.
| Format | Example line |
|---|---|
| GNU | HASH NAME or HASH *NAME |
| BSD | SHA256 (NAME) = HASH |
| bare | a file whose only non-empty line is a hash of the right length (Alpine) |
The download recipe of a system runs when its cache link is older than its .url or .filename file. make follows the link to the image, so after an upgrade of image-garden or an edit of .image-garden.mk, which rewrite .url, the recipe runs on every make: the helper finds the list and the image, fetches nothing and checks the image again (run). This lasts until the image itself is downloaded again.
A named instance is a new system made from an existing one: the same download, its own cloud-init, disk and .run script.
data/*.ini, "which are all but Ubuntu Core" (README.md:976-979).mk/020-instances.mk documents define-instance at its top (020-instances.mk:1-28).webserver and database instances.$(eval $(call define-instance,ubuntu-cloud-24.04,webserver)) makes ubuntu-cloud-24.04@webserver.ARCH; with a base like ubuntu-cloud-24.04.x86_64 that architecture is used.
define-instance takes the base as $(1): when no metadata exists for that exact name, it appends GARDEN_ARCH; otherwise the last dot-separated part is the architecture. The instance's full name is BASE@NAME.ARCH (020-instances.mk:29-45). The QEMU rules follow the base's Arch= instead, which differs from the name only for the .ppc64el systems (020-instances.mk:53-56)..image-garden.mk, which mk/999-local.mk includes (999-local.mk:4-5).An instance has its own .meta-data, .user-data, .seed.iso, firmware copies, .qcow2 and .run; its overlay sits on the base system's download.
GARDEN_SYSTEMS, and to all:: when GARDEN_ARCH matches the base system's Arch= (020-instances.mk:58-65), and writes its meta-data and user-data rules (020-instances.mk:67-79)..run script needs the instance's own .efi-code.qcow2 and .efi-vars.qcow2, and its .qcow2 is qemu-img create -f qcow2 -b $(GARDEN_DL_DIR)/GROUP/BASE.qcow2, the base system's download link, followed by the provisioning boot with the instance's seed (020-instances.mk:84-103). BIOS and platform bases have matching rules without firmware (020-instances.mk:105-146).clean and distclean remove the instance's files, not the download (020-instances.mk:148-155); make distclean removes the download too, through the base system's own rule (see where image-garden keeps its files).Group, release, architecture and boot type come from the base system's entry in image-garden's list of systems. Users stay the same; the host name becomes ubuntu-24-04-webserver.
define-instance reads _BASE_group, _group_upper, _release, _boot and _arch of the base system (020-instances.mk:47-56), which rulegen.py --systems-meta writes into data/000-systems.mk for every system in data/*.ini (rulegen.py:825-833).Arch=, not the suffix of its name: "ppc64 systems are named .ppc64el" (020-instances.mk:53-56). The instance's name keeps the suffix, ubuntu-cloud-24.04@webserver.ppc64el, and it joins all when GARDEN_ARCH is that architecture (020-instances.mk:61-65). Run: the launcher made for ubuntu-cloud-24.04@webserver.ppc64el runs qemu-system-ppc64.--query lists the base system's users, root/root and the group's user: the instance rules pass the user mode root distro, as rulegen.py does (020-instances.mk:89, 010-qemu.mk:80-88). Run: ubuntu-cloud-24.04@webserver.x86_64.run --query printed root and ubuntu with their passwords.CLOUD_INIT_HOSTNAME: group, release and instance joined by dashes, with dots and pluses turned into dashes (010-qemu.mk:94-97): ubuntu-24-04-webserver, as the README says (README.md:988-993). The user-data's hostname (010-qemu.mk:196) and the meta-data's local-hostname and instance-id use it alike (010-qemu.mk:99-104, 020-instances.mk:68).data/*.ini, so they have no such metadata and have no instances. The README: "define-instance with an Ubuntu Core system lists the instance in list-systems, but make has no rule for it" (README.md:976-979, 020-instances.mk:9-10).UBUNTU_24.04@webserver_… changes this instance only; UBUNTU@webserver_… every webserver instance of Ubuntu. The base system keeps its own template.
GROUP_RELEASE@INSTANCE_… and GROUP@INSTANCE_… are tried first (010-qemu.mk:293-298).nginx and libssl-dev for ubuntu-cloud-24.04@webserver, and its CENTOS@old-server_… example applies to every @old-server instance of any CentOS release (README.md:1022-1044).In spread.yaml, ubuntu-cloud-24.04-at-webserver; the allocate hook maps -at- back to @. Credentials are the base system's.
-plus- into + and the first -at- into @, then runs image-garden allocate --spread "$SYSTEM"."$ARCH" (spread.yaml:45-47). The README explains the escaping (README.md:720-733).--query, as every .run script does (020-instances.mk:89); spread itself takes the user and password from spread.yaml, which the garden backend's systems list for each system (spread.yaml:60-66).@ is the README's advice ("escape them for compatibility"); spread's own rules were not read for this map.Next: picking a template, several systems from one base image, and spread names.
Read in mk/020-instances.mk, mk/010-qemu.mk and the README of image-garden at the commit in garden.commit ("code"); the example names are illustrative. The launchers of ubuntu-cloud-24.04@webserver.x86_64 and ubuntu-cloud-24.04@webserver.ppc64el were generated and asked --query ("run").
$(eval $(call define-instance,ubuntu-cloud-24.04,webserver)) on x86_64 | |
|---|---|
| System name | ubuntu-cloud-24.04@webserver.x86_64 |
| In spread.yaml | ubuntu-cloud-24.04-at-webserver |
| Downloaded image | the base system's: ~/.cache/image-garden/dl/ubuntu/ubuntu-cloud-24.04.x86_64.qcow2 (a link) |
| Its own files | .meta-data, .user-data, .seed.iso, .efi-code.qcow2, .efi-vars.qcow2, .qcow2, .qcow2.log, .run |
| Group, release, architecture, boot | ubuntu, 24.04, x86_64, efi, from the base system's metadata |
| Users | ubuntu/ubuntu and root/root, as the base system; --query lists them |
| Host name (user-data and meta-data) | ubuntu-24-04-webserver |
| Templates tried | UBUNTU_24.04@webserver_…, UBUNTU@webserver_…, UBUNTU_24.04_…, UBUNTU_…, then the common one |
define-instance reads the base system's metadata from data/000-systems.mk, which covers the systems of data/*.ini: every system but Ubuntu Core's, which have no instances (README.md:976-979).Arch=: an instance of ubuntu-cloud-24.04.ppc64el is named …@NAME.ppc64el and runs qemu-system-ppc64 (020-instances.mk:53-56).GARDEN_ARCH, the host's by default.make clean removes the instance's files; the download stays. make distclean removes the download as well..image-garden.mk rebuilds every system's image, instances included: see changing what cloud-init does.image-garden make SYSTEM.run builds a launcher; SYSTEM.qcow2 builds only the prepared disk. The command is the same in every install.
ubuntu-cloud-24.04.x86_64.run and runs it (README.md:69-83); the goals SYSTEM.ARCH.qcow2 and SYSTEM.ARCH.run are described in README.md:552-577.docker run … image-garden:latest make … or run inside it; see running image-garden in a container.image-garden make checks /dev/kvm, then runs make -f image-garden.mk with GARDEN_ITSELF and GARDEN_PROJECT_DIR, passing your arguments on.
kvm_check prints a large WARNING when /dev/kvm exists but is not writable, with advice: sudo usermod -aG kvm $LOGNAME, or in CI ($CI set) sudo chmod 666 /dev/kvm. It does not stop the build (image-garden:670-709).image-garden make runs exec make --warn-undefined-variables GARDEN_ITSELF=… GARDEN_PROJECT_DIR=… -f $GARDEN_INCLUDE/image-garden.mk -C <dir> "$@", where <dir> is .image-garden when it exists (image-garden:982-993)..image-garden.mk, if there is one (999-local.mk:4-5).QEMU_MEM_SIZE=4096 are make variables: pass them on the command line or set them in .image-garden.mk (README.md:882-888).Banners: Download and verify base image, Prepare writable qcow2, Provision, Generate launcher script. The console of the provisioning boot is kept in SYSTEM.qcow2.log.
GARDEN_LOG_SECTION: a border of =, then | %-44.44s %31.31s | with the title and date -u '+%a, %d %b %Y %H:%M:%S %z', so titles longer than 44 characters are cut (000-garden.mk:32-36). In CI ($CI set) an extra empty row is printed so log viewers keep the gap.tee SYSTEM.qcow2.log (rulegen.py:609).SYSTEM.run has the disk as an order-only prerequisite (rulegen.py:593-596).image-garden make list-systems lists every system; image-garden make prints help with a random example; image-garden prints the usage of every command.
help is the default goal: it prints Usage: image-garden make <SYSTEM>.{run,qcow2} and a system picked with $RANDOM (000-garden.mk:43, 000-garden.mk:72-83).list-systems prints GARDEN_SYSTEMS, one per line (000-garden.mk:85-87); named instances add themselves to that list (README.md:536-540).image-garden with no arguments, -h or --help prints the usage of every command (image-garden:889-908).image-garden make -n SYSTEM.run shows the commands without running them. -B rebuilds everything except complete downloads.
-n displays commands without executing them; -B forces a rebuild, but a complete download is not repeated (README.md:514-519). -n and --dry-run are the same GNU make option.-n prints it in full.With a .image-garden/ directory every generated file goes there. .image-garden.mk is read by make, and changing it rebuilds the images that depend on it.
image-garden make changes into .image-garden/ when that directory exists (image-garden:982-993); the README lists the eight files made per system (README.md:820-837).$GARDEN_DL_DIR, by default ~/.cache/image-garden/dl (image-garden:20-29).SYSTEM.user-data depends on the project's .image-garden.mk, so editing it rebuilds the user-data, the seed and the disk of every system (rulegen.py:467-468, README.md:854-858).Next: the .run script, the serial console, the target chain, allocate, where files live, .image-garden.mk and the support matrix.
Read in the image-garden source at the commit in garden.commit ("code"): the image-garden script, mk/*.mk, rulegen.py, the README and the man page image-garden.1. Where the documentation and the code differ, this page follows the code and says so. Nothing was run for this page.
| Command | What it does |
|---|---|
image-garden make [MAKE-OPTIONS] [GOAL…] | checks /dev/kvm, then runs GNU make on image-garden.mk, in .image-garden/ when it exists (image-garden:982-993) |
image-garden allocate [-p PORT] [--premade] [--nice] [--spread] SYSTEM.ARCH [QEMU-OPTION…] | makes the system unless --premade, starts it in the background with -snapshot and SSH on a local port, prints the address (image-garden:996-1219) |
image-garden discard ADDRESS | stops the machine at localhost:PORT and removes its pid file and TPM state copy (image-garden:1221-1274) |
image-garden discard -a | stops every allocated machine |
image-garden ps [--all] [--stale] | lists allocated machines: address, PID, memory and system; --stale those whose QEMU is gone, --all every entry (image-garden:1276-1358) |
image-garden rebase SYSTEM.ARCH | points a prepared disk's backing file at the matching download in $GARDEN_DL_DIR, with qemu-img rebase -u, so the old download need not exist; takes the system name or its .qcow2 file; fails if there is no matching download (image-garden:943-980) |
image-garden version, --version | prints the version (image-garden:909-911) |
image-garden news [N] | prints the last N releases from NEWS, then the snap's or the container's notes; N defaults to 1 (image-garden:912-942) |
image-garden download-with-sha512sums URL [SUMS-URL] [DIR] [FILENAME] | downloads and checks against a SHA512SUMS list; the list defaults to SHA512SUMS next to the image, DIR to $GARDEN_DL_DIR (image-garden:358-362) |
image-garden download-with-sha256sums URL [SUMS-URL] [DIR] [FILENAME] | the same with a SHA256SUMS list (image-garden:460-464) |
image-garden download-with-sha256sum URL SHA256 [DIR] [FILENAME] | the same with one known hash, which is required (image-garden:562-577) |
image-garden download URL [DIR] [FILENAME] | downloads without a checksum (image-garden:627-630) |
image-garden, -h, --help | prints the usage (image-garden:889-908) |
Options of allocate (README.md:404-424):
| Option | Meaning |
|---|---|
-p PORT | try this port first; a random free port in 5000-9999 otherwise |
--premade | do not make the system, use the images that are there |
--nice | run QEMU with nice; on by default in x11 and wayland sessions |
--spread | print <ADDRESS localhost:PORT> and <FATAL …> for spread, and wait for SSH first |
| Goal | What it makes (README.md:506-577) |
|---|---|
help | the default: usage and a random example |
list-systems | every system, with its architecture, including named instances |
SYSTEM.ARCH.run | the launcher, with everything it needs |
SYSTEM.ARCH.qcow2 | only the prepared disk |
all | every system of the host's architecture |
fetch | every download of the host's architecture, for working offline |
clean | removes generated images, logs and support files here; keeps downloads |
distclean | clean, and removes the downloads from the cache |
Useful make options: -n (print, do not run), -B (make again; complete downloads are kept), -j (several systems at once).
| Use | Effect |
|---|---|
./SYSTEM.run | boots in the foreground on the serial console; changes are kept |
./SYSTEM.run -snapshot | the same, but changes are thrown away when QEMU exits |
./SYSTEM.run --query | prints vm.memory_mb and system.users.N.username and .password, then exits (010-qemu.mk:57-92) |
./SYSTEM.run ARGS… | any other arguments are added to the QEMU command (010-qemu-x86_64.mk:105) |
./SYSTEM.run of a +tpm system | must be run from its own directory, next to SYSTEM.tpm/ |
| Variable | Used by | Meaning |
|---|---|---|
XDG_CACHE_HOME | all | base of the cache; default $HOME/.cache |
GARDEN_CACHE_DIR | all | the cache; default $XDG_CACHE_HOME/image-garden, in the snap $SNAP_USER_COMMON/cache (image-garden:20-29) |
GARDEN_DL_DIR | all | downloaded images; default $GARDEN_CACHE_DIR/dl |
PKGPROXY_URL | make, downloads | a pkgproxy for guests and image downloads |
GARDEN_DL_PKGPROXY | downloads | a pkgproxy for image downloads alone, http://host:port or unix:/path; set empty to turn downloads through pkgproxy off (image-garden:31-58) |
XDG_RUNTIME_DIR | allocate, discard, ps | pid files, ports and locks, under image-garden/; default /run (image-garden:60-73) |
QEMU_SNAPSHOT_OPTION | allocate | default -snapshot; set empty to keep changes (image-garden:1154) |
GARDEN_SSH_WAIT_TIMEOUT | allocate --spread | seconds to wait for SSH; default 600 (image-garden:1173) |
GARDEN_MEMORY_RESERVE | allocate | MB kept for the host in the memory check; default 2048 in x11 and wayland sessions, 1024 otherwise (image-garden:733-745) |
XDG_SESSION_TYPE | allocate | x11 or wayland turn on nice and the larger reserve |
GARDEN_TPM_RUN_DIR | .run of a +tpm system | where swtpm runs; allocate sets it per port (image-garden:1110-1111) |
QEMU_MEM_OPTION | .run | default -m 2048 (010-qemu.mk:9, 010-qemu.mk:12) |
QEMU_SMP_OPTION | .run | default -smp N: 4 on the host's own architecture, 1 otherwise |
QEMU_DISPLAY_OPTION | .run | default -nographic; allocate uses -display none (010-qemu.mk:13, image-garden:1105) |
QEMU_BOOT_FIRMWARE_OPTION, QEMU_STORAGE_OPTION, QEMU_RNG_OPTION, QEMU_NET_OPTION, QEMU_TPM_OPTION, QEMU_ACCEL_MACHINE_PROP | .run | replace one part of the QEMU command each (010-qemu-x86_64.mk:72-80) |
QEMU_NETDEV_USER_EXTRA | .run | appended to -netdev user; allocate uses it for the SSH port forward (image-garden:1107) |
QEMU_MEM_SIZE, QEMU_IMG_SIZE, QEMU_SMP_<ARCH>, QEMU_CPU_<ARCH> | make | memory, disk size, CPUs and CPU model baked into new launchers; pass on the make command line (README.md:882-899) |
QEMU_SYSTEM_<ARCH>, QEMU_IMG, XORRISO, CURL, SWTPM | make | the tools to run (README.md:915-920) |
The README and the man page list the .run variables, QEMU_NET_OPTION, QEMU_NETDEV_USER_EXTRA, QEMU_STORAGE_OPTION, QEMU_TPM_OPTION and QEMU_ACCEL_MACHINE_PROP among them (README.md:922-947, image-garden.1:638-679); the scripts read them as listed (010-qemu-x86_64.mk:72-80).
ubuntu-cloud-24.04.x86_64.qcow2 is a copy-on-write overlay: writes go to it, unchanged blocks are read from the download, which stays as it was.
X.qcow2 is created with qemu-img create -f qcow2 -b $(GARDEN_DL_DIR)/GROUP/X.qcow2 -F qcow2 X.qcow2 $(QEMU_IMG_SIZE) (rulegen.py:601-604); QEMU_IMG_SIZE = 64G (010-qemu.mk:8).qemu-img create -f qcow2 -b ~/.cache/image-garden/dl/ubuntu/ubuntu-cloud-24.04.x86_64.qcow2 -F qcow2 ubuntu-cloud-24.04.x86_64.qcow2 64G: 64 GiB virtual, about 200 KiB on disk when made.
$(QEMU_IMG) create -f qcow2 -b $< -F qcow2 $@ $(QEMU_IMG_SIZE), where $< is $(GARDEN_DL_DIR)/GROUP/X.qcow2, the link, and QEMU_IMG is qemu-img from PATH, required when make starts (rulegen.py:601-604, 010-qemu.mk:3).QEMU_IMG_SIZE = 64G (010-qemu.mk:8). It is a make variable, so image-garden make QEMU_IMG_SIZE=128G X.run would override it (derived from GNU make's rules for command-line variables; not documented).GARDEN_DL_DIR is an absolute path by default, so the overlay records the absolute path of the link; image-garden make -n shows it in full.qemu-img create with these options on a small backing file and qemu-img info on the result: 64 GiB virtual, 196 KiB on disk.growpart and resizefs defaults (derived); image-garden's user-data does not configure it.X.qcow2 → DL/ubuntu/X.qcow2 (a link) → noble-server-cloudimg-amd64.img. A moved cache needs image-garden rebase; a changed download breaks every overlay on it.
$(GARDEN_DL_DIR)/GROUP/X.qcow2, the link made by the download rule with GARDEN_SYMLINK to the downloaded file (rulegen.py:494-514, rulegen.py:601-604).ubuntu-core-R-ARCH.img.xz is converted by %.qcow2: %.img.xz inside GARDEN_LOCKED_RECIPE (010-qemu.mk:304-347), and the system links point at the converted file (050-ubuntu-core.mk:273-289). A second make that waited prints "… was made by another image-garden make". See Ubuntu Core.image-garden rebase, given the system name or the .qcow2 file, reads full-backing-filename from qemu-img info --output=json, finds a file of the same name under $GARDEN_DL_DIR and runs qemu-img rebase -u -b NEW -F qcow2, which rewrites the path without opening the old base; it fails with "cannot find the backing image" when there is none (image-garden:943-980)./home/you on the slide stands for your home directory.The provisioning boot is the launcher's QEMU command plus -drive file=X.seed.iso,…,readonly=true,media=cdrom, piped through tee X.qcow2.log under set -o pipefail.
set -o pipefail && $(call QEMU_SYSTEM_X86_64_EFI_CMDLINE,X.qcow2,X.efi-code.qcow2,X.efi-vars.qcow2) -drive file=X.seed.iso,format=raw,id=drive1,if=none,readonly=true,media=cdrom -device virtio-blk,drive=drive1 2>&1 | tee X.qcow2.log, with SHELL=bash for the target (rulegen.py:601-609).set -o pipefail: the rules rulegen.py writes, named instances (020-instances.mk:94-103) and Ubuntu Core, with and without a TPM (050-ubuntu-core.mk:37-53). A QEMU that fails to start or exits with an error fails the step, and .DELETE_ON_ERROR removes the half-made overlay.QEMU_SYSTEM_X86_64_EFI_CMDLINE reads ${QEMU_MEM_OPTION=…}, ${QEMU_SMP_OPTION=…}, ${QEMU_DISPLAY_OPTION=…} and the other option variables from the environment, the same names the launcher uses (010-qemu-x86_64.mk:13-26). The default display is -nographic and the default memory -m 2048 (010-qemu.mk:9-13). The command on the slide is abridged; image-garden make -n prints it in full.cidata label (010-qemu.mk:263-278).power_state (010-qemu.mk:190-195); see provisioning runs once. The +tpm systems also start swtpm for this boot (050-ubuntu-core.mk:70-106).QEMU_MEM_OPTION in the environment of image-garden make is an example; the variables are listed in the .run script.ubuntu-cloud-24.04.x86_64.qcow2.log keeps the console of the provisioning boot. It survives a failed boot, is overwritten by the next one, and is removed by make clean.
2>&1 | tee X.qcow2.log; tee without -a truncates the file, so each boot writes it anew (rulegen.py:609-609)..DELETE_ON_ERROR leaves it when it deletes the failed X.qcow2 (000-garden.mk:4-7).clean:: runs rm -f *.log in the directory make runs in (000-garden.mk:48-50); that also removes the logs allocate writes.message of the user-data's power_state (010-qemu.mk:190-195). The other lines on the slide stand for output that depends on the image (derived). The grep command is an example.X.qcow2 is remade when the download link, the seed or the firmware copies are newer. The new overlay starts empty: changes made by booting .run without -snapshot are lost.
X.qcow2 depends on $(GARDEN_DL_DIR)/GROUP/X.qcow2, X.seed.iso, X.efi-code.qcow2 and X.efi-vars.qcow2 (rulegen.py:601-602). The seed depends on the user-data and meta-data (010-qemu.mk:268-268), and they on the makefiles and .image-garden.mk (rulegen.py:460-471); the firmware copies on the host firmware (010-qemu-x86_64.mk:316-329).qemu-img create writes a new, empty overlay over the old file..run alone keeps changes in the overlay; allocate adds -snapshot unless QEMU_SNAPSHOT_OPTION says otherwise (image-garden:1153-1154).make -n: deleting the seed ISO gives the seed, the overlay and the provisioning boot.Next: provisioning runs once, the target chain, rebase, named instances and the .run script.
The rules were read in the image-garden source at the commit in garden.commit ("code"). The sizes were taken by running qemu-img create and qemu-img info with the same options on a small backing file, and the rebuild cases by running image-garden make -n on a scratch project ("run"). How qcow2 overlays and GNU make behave in general is marked "derived".
For ubuntu-cloud-24.04.x86_64, with DL the download cache:
qemu-img create -f qcow2 -b DL/ubuntu/ubuntu-cloud-24.04.x86_64.qcow2 -F qcow2 ubuntu-cloud-24.04.x86_64.qcow2 64G
set -o pipefail && exec qemu-system-x86_64 -cpu max -machine q35,accel=… \
-m 2048 -smp … -nographic \
-drive if=pflash,format=qcow2,unit=0,file=ubuntu-cloud-24.04.x86_64.efi-code.qcow2,readonly=on \
-drive if=pflash,format=qcow2,unit=1,file=ubuntu-cloud-24.04.x86_64.efi-vars.qcow2 \
-drive file=ubuntu-cloud-24.04.x86_64.qcow2,if=none,format=qcow2,id=drive0,media=disk,cache=writeback,discard=unmap \
-device virtio-blk,drive=drive0,bootindex=0 \
-device virtio-rng-pci -netdev user,id=netdev0 … \
-drive file=ubuntu-cloud-24.04.x86_64.seed.iso,format=raw,id=drive1,if=none,readonly=true,media=cdrom \
-device virtio-blk,drive=drive1 \
2>&1 | tee ubuntu-cloud-24.04.x86_64.qcow2.log
Abridged from image-garden make -n; the accelerator is kvm:tcg when QEMU knows KVM, else tcg, and the SMP default depends on the host (rulegen.py:601-609, 010-qemu-x86_64.mk:13-26).
| Variable | Default | Kind | Effect on step nine |
|---|---|---|---|
QEMU_IMG_SIZE | 64G | make variable | the virtual size of the overlay |
QEMU_IMG | qemu-img on PATH | make variable | the program that creates the overlay |
QEMU_MEM_OPTION | -m 2048 | environment | memory of the provisioning boot |
QEMU_SMP_OPTION | -smp N | environment | CPUs of the provisioning boot |
QEMU_DISPLAY_OPTION | -nographic | environment | where the console goes |
The environment variables are the launcher's; see the .run script for the rest.
| Input | Newer when |
|---|---|
| the cache link, followed to the image | the image is downloaded again (a new file name after an upgrade, or a missing or failed file) |
X.seed.iso | the user-data or meta-data are rewritten: an upgrade of image-garden, an edit of .image-garden.mk |
X.efi-code.qcow2, X.efi-vars.qcow2 | the firmware copies are made again, for example after make clean or newer host firmware |
X.qcow2 itself | it is missing, for example after a failed provisioning boot |
The launcher is not rewritten by a new overlay; see the target chain.
| File | What it is |
|---|---|
X.qcow2 | the overlay, about 200 KiB when created, then as large as what the guest wrote |
X.qcow2.log | the console of the last provisioning boot |
DL/GROUP/X.qcow2 | the link the overlay names as its backing file |
DL/GROUP/<download> | the image, read-only for every overlay on it |
./ubuntu-cloud-24.04.x86_64.run --query prints the machine's memory and its users, one key=value per line, and exits before QEMU starts.
--query is checked first thing in every launcher: when it is the first argument, the script prints its properties and runs exit 0, before any QEMU option is computed (010-qemu.mk:57-90). There is no image-garden query command: the mode belongs to each .run script.spread.yaml gives each system's username and password by hand (spread.yaml:60-72).image-garden make X.run makes it, and with the default GARDEN_RUN_REQUIRES_QCOW2=1 that makes the disk first (010-qemu.mk:14).Most systems list root/root as user 0 and the distribution's user as user 1. ubuntu-core-* lists only ubuntu/ubuntu, as user 0.
image-garden.mk of the commit in garden.commit and run with --query; the output is the one on the slide, and matches the QUERY file's example (QUERY:55-69).case on a user mode: only:ubuntu prints user 0 ubuntu/ubuntu; root distro prints user 0 root/root and user 1 named after the group, with its name as the password (010-qemu.mk:79-88).root distro and it passes the group as the user name (rulegen.py:127, rulegen.py:596); the Ubuntu Core rules pass only:ubuntu (050-ubuntu-core.mk:25).group.key=value (QUERY:8-9, QUERY:31-53).-m 2048, -m 512M and -m 4G give 2048, 512 and 4096. Other forms give vm.memory_mb=error: unsupported format … with exit status 0.
${QEMU_MEM_OPTION=-m 2048}: the default applies only when the variable is unset; set to an empty string, it gives the error line (010-qemu.mk:66, default from 010-qemu.mk:9-12).-m N, -m NM or -m Nm, -m NG or -m Ng (times 1024); anything else prints vm.memory_mb=error: unsupported format "…" and exits 0 (010-qemu.mk:67-77, QUERY:19-29).QEMU_MEM_OPTION="-m 4G" gave vm.memory_mb=4096, -m 4096M gave 4096, and -m size=4G gave vm.memory_mb=error: unsupported format "-m size=4G" with exit status 0, followed by no user lines.-m size=4G (derived from QEMU's option syntax); the query does not.allocate reads vm.memory_mb for its memory check. snapcraft-vm, rockcraft-vm and charmcraft-vm log in as system.users.0, with sudo -H unless it is root.
memory_check runs ./X.run --query 2>/dev/null, keeps vm.memory_mb, skips the check when the value is empty or an error, and warns when it exceeds (MemAvailable − reserve) / 1.5; the reserve is GARDEN_MEMORY_RESERVE, else 2048 MB in an x11 or wayland session and 1024 MB otherwise. The warning waits 30 seconds (image-garden:711-782). It runs once the launcher exists (image-garden:1066-1068).system.users.0.username and .password right after allocate --spread, stops with "cannot log into SYSTEM: its image names no user" when there is none, and uses sudo -H when the user is not root (snapcraft-vm:372-381); rockcraft-vm and charmcraft-vm do the same (rockcraft-vm:356-363, charmcraft-vm:397-404).sshpass -e ssh … -p PORT USER@localhost (snapcraft-vm:231-242).Read stdout only (the script runs with set -x), find lines by key, test for error:, and log in as system.users.0: ubuntu on Ubuntu Core, root elsewhere.
set -xeu (010-qemu.mk:59), so bash traces each command of the query to standard error; allocate reads it with 2>/dev/null (image-garden:720).error: as no answer (image-garden:722-725).case on the launcher's user mode: only:ubuntu prints ubuntu as user 0 alone; root distro prints root as user 0 and the group's user as user 1 (010-qemu.mk:80-88). Ubuntu Core's launchers pass only:ubuntu (050-ubuntu-core.mk:25); rulegen.py's and the named instances' pass root distro (020-instances.mk:89, also :110 and :131). Run: ubuntu-cloud-24.04@webserver.x86_64.run --query printed the same four user lines as ubuntu-cloud-24.04.x86_64.run --query. QUERY says every .run script exposes the users (QUERY:31-53).EMIT_QEMU_RUN_SCRIPT_QUERY_PREAMBLE(launcher, download dir, root distro or only:ubuntu, group). rulegen.py and the instance rules pass root distro, Ubuntu Core only:ubuntu.
EMIT_QEMU_RUN_SCRIPT_QUERY_PREAMBLE writes the #!/bin/bash line, set -xeu, a warning comment naming the download directory and the --query block (010-qemu.mk:57-92).{img.query_users}, default root distro (rulegen.py:127, rulegen.py:596, and the other architectures' rules); the Ubuntu Core rules with only:ubuntu (050-ubuntu-core.mk:25, :32, :63); the instance rules with root distro as well (020-instances.mk:89, :110, :131).case word is "$(3)", and the arm is root\ distro): an escaped space in a pattern matches the plain root distro the callers pass (010-qemu.mk:80-88). Run: an instance's launcher printed root and the group's user, as its base's did.tests/check-query.sh checks that vm.memory_mb is numeric, that each password equals its user, root and the group's user for ordinary systems, and only ubuntu for Ubuntu Core (check-query.sh:1-111). CI runs it on each launcher it builds (.gitlab-ci.yml:592-593, run-systems.sh:64); named instances are not among them.Next: allocate's memory check, the craft components' login, the users in the guest, and named instances.
Read in the image-garden source at the commit in garden.commit ("code"). The outputs were run: the launchers of ubuntu-cloud-24.04.x86_64 and of an instance ubuntu-cloud-24.04@webserver.x86_64 were generated from that commit's image-garden.mk and run with --query. Nothing was booted.
| Key | Value | Systems |
|---|---|---|
vm.memory_mb | memory in MB from QEMU_MEM_OPTION (default -m 2048), or error: unsupported format "…" | every launcher |
system.users.0.username, .password | root, root | systems made by rulegen.py, and their named instances |
system.users.1.username, .password | the group, such as ubuntu or fedora, twice | systems made by rulegen.py, and their named instances |
system.users.0.username, .password | ubuntu, ubuntu | ubuntu-core-* |
Sources: 010-qemu.mk:57-92, QUERY.
QEMU_MEM_OPTION | vm.memory_mb |
|---|---|
| unset | 2048 |
-m 2048 | 2048 |
-m 512M, -m 512m | 512 |
-m 4G, -m 4g | 4096 |
empty, -m size=4G, anything else | error: unsupported format "…", exit 0 |
query=$(./ubuntu-cloud-24.04.x86_64.run --query 2>/dev/null) mem=$(sed -n 's/^vm\.memory_mb=//p' <<<"$query") user=$(sed -n 's/^system\.users\.0\.username=//p' <<<"$query") password=$(sed -n 's/^system\.users\.0\.password=//p' <<<"$query") case "$mem" in error:*|'') echo "cannot tell the memory size" >&2 ;; esac
The lookups follow snapcraft-vm (snapcraft-vm:374-376); the memory test follows allocate (image-garden:720-725).
| Reader | Keys | Use |
|---|---|---|
image-garden allocate | vm.memory_mb | memory check before starting |
| snapcraft-vm, rockcraft-vm, charmcraft-vm | system.users.0.* | SSH login, sudo -H unless root |
tests/check-query.sh | all | image-garden's CI |
X.qcow2 records its base as a full path into GARDEN_DL_DIR. image-garden rebase points it at the base in this machine's download directory.
qemu-img create -f qcow2 -b $(GARDEN_DL_DIR)/GROUP/X.qcow2 -F qcow2, so the path it records is the full path of the system's link in the download directory (rulegen.py:601-604). Run: qemu-img info on such an overlay shows that path as "backing file".$GARDEN_DL_DIR", for a CI cache used on another system "where everything is compatible except the effective location of the download directory" (README.md:434-448).GARDEN_DL_DIR is $GARDEN_CACHE_DIR/dl, and the cache directory differs between the snap, a native install and the container (image-garden:20-29)./cache-a and /cache-b on the slides are example paths.rebase reads full-backing-filename from qemu-img info, finds that base name under GARDEN_DL_DIR and runs qemu-img rebase -u -b NEW -F qcow2 X.qcow2.
$GARDEN_PROJECT_DIR/.image-garden/ARG when that directory exists, else ARG, with .qcow2 added when only that file exists; a missing file gives "image-garden: cannot find image at PATH" (image-garden:951-964).qemu-img info --output=json with grep, cut and sed, without jq; the new base is find "$GARDEN_DL_DIR" -name BASENAME -print -quit, the first match anywhere below the directory (image-garden:969-971).execs qemu-img rebase -u -b NEW -F qcow2 IMAGE (image-garden:972-980). Run: the usage, "cannot find image", "cannot rebase without downloaded image directory" and "re-basing" messages, with the script at garden.commit and a host qemu-img.$QEMU_IMG when set, else qemu-img from PATH, for both the info and the rebase call (image-garden:970, image-garden:980), as make's rules use $(QEMU_IMG).ubuntu-cloud-24.04.x86_64.qcow2 in dl/ubuntu/; it exists once the system's download rule has run.image-garden rebase ubuntu-cloud-24.04.x86_64 and image-garden rebase ubuntu-cloud-24.04.x86_64.qcow2 both re-base .image-garden/ubuntu-cloud-24.04.x86_64.qcow2.
image-garden rebase SYSTEM.ARCH (image-garden:893, image-garden:946); so do the README (README.md:434-440) and the man page (image-garden.1:19). image-garden-action passes SYSTEM.$(uname -m).qcow2 (action.yaml:442).$GARDEN_PROJECT_DIR/.image-garden/ in front when that directory exists; when no file has that exact name but one with .qcow2 added does, rebase takes that one (image-garden:951-964). The "cannot find image at PATH" message shows the path without .qcow2..image-garden/ubuntu-cloud-24.04.x86_64.qcow2, rebase ubuntu-cloud-24.04.x86_64 re-based it; rebase debian-cloud-13.x86_64 printed "image-garden: cannot find image at …/.image-garden/debian-cloud-13.x86_64" and exited 1. tests/check-rebase.sh runs both forms (tests/check-rebase.sh:21-39)..image-garden/ present, an argument that already starts with .image-garden/, or an absolute path, gets the directory put in front again and is not found (derived from image-garden:954-956)..image-garden/, the argument is a path from the current directory, and the same .qcow2 rule applies (derived from image-garden:953-960).rebase runs qemu-img rebase -u, which rewrites the backing path without opening the old base, so it works when the old cache is gone.
qemu-img rebase -u -b NEW -F qcow2 IMAGE; its comment: "Unsafe mode only rewrites the backing file name: the old backing file is usually gone, which is why the image needs rebasing, and the new one is the same download" (image-garden:976-980). The NEWS entry: rebase "works when the old download directory is gone" (NEWS:5-6).-u, qemu-img compares the old and the new backing chains and writes the differences into the image, so it opens the old one (qemu-img's documented "safe mode"). A safe-mode rebase with the old directory moved away stopped with "Could not open backing file: Could not open '…/old/dl/ubuntu/ubuntu-cloud-24.04.x86_64.qcow2': No such file or directory" (run with a host qemu-img).qemu-img info showed the new backing file. tests/check-rebase.sh checks the same, for both argument forms (tests/check-rebase.sh:21-39).-u does not compare contents. The new base is found by the file name of the old one, the system's link in dl/GROUP/ (image-garden:970-971); if that link points at a different build than the one the image was made from, the image would read changed data under its own changes (derived). After a restore, image-garden make runs before rebase and decides whether the prepared image is still current: see the caching deck./cache-a and /cache-b on the slide are example paths.Restore .image-garden/, image-garden make, image-garden rebase X.qcow2, then boot. On GitHub's runners the path does not change.
.image-garden/ without its logs when cache-prepared-images is true (action.yaml:116-123), runs image-garden make for the image, launcher, user-data, meta-data and seed (action.yaml:420-435), then image-garden rebase SYSTEM.$(uname -m).qcow2 (action.yaml:436-442), then spread.~/snap/image-garden/common/cache/dl, the snap's download directory (action.yaml:416). That every GitHub-hosted runner has the same home directory, so the same path, is derived.cache-prepared-images is true; its TODO says it should run only on a hit (action.yaml:436-439)..image-garden.mk for that (action.yaml:124-152). See the caching deck.Next: the overlay, the GitHub action's caches, and where image-garden keeps its files.
Read in the image-garden source at the commit in garden.commit ("code"). Every message was run: the script at that commit and a host qemu-img on a scratch overlay of an empty qcow2, with the download directory removed or missing, and tests/check-rebase.sh passed. That GitHub runners share one home path, and when an unsafe rebase is correct, are derived.
image-garden rebase SYSTEM.ARCH image-garden rebase SYSTEM.ARCH.qcow2
The argument is looked up in .image-garden/ when the project has that directory, otherwise from the current directory. When no file has exactly that name, rebase adds .qcow2 (image-garden:951-964). image-garden-action passes the .qcow2 form.
${QEMU_IMG:-qemu-img} info --output=json IMAGE # full-backing-filename
find "$GARDEN_DL_DIR" -name BASENAME -print -quit # the first match
${QEMU_IMG:-qemu-img} rebase -u -b NEW -F qcow2 IMAGE # rewrites the path only
-u does not open the old base, so rebase works after the old download directory is gone (image-garden:969-980). It does not compare the two bases either: the new one is trusted because it has the same file name, the system's link to its verified download.
| Message | Cause |
|---|---|
Usage: image-garden rebase SYSTEM.ARCH (exit 0) | not exactly one argument |
image-garden: cannot find image at PATH | neither PATH nor PATH.qcow2 exists, for example a system never prepared |
image-garden: cannot rebase without downloaded image directory: DIR | GARDEN_DL_DIR does not exist |
image-garden: cannot find the backing image of IMAGE, NAME, in DIR | no file named after the backing file under GARDEN_DL_DIR, or the image has no backing file |
image-garden: re-basing IMAGE on top of NEW | about to run qemu-img rebase -u |
tests/check-rebase.sh makes an overlay on a base in one directory, moves the base to another and removes the first, then runs rebase with demo.x86_64 and with demo.x86_64.qcow2 and checks the new backing file (tests/check-rebase.sh:1-39). make check runs it (Makefile:108-109).
The .run script is plain bash with the exact QEMU command for one system. Read it, copy it, or change it through environment variables.
.run scripts contain the exact qemu commands (README.md:22-23)..run rule of an x86_64 EFI system writes the --query preamble, then the run command, and makes the file executable (rulegen.py:593-600). It is the target you name in the quick start (README.md:69-89).qemu-system-x86_64 outside the snap and image-garden.qemu-system-x86-64 inside it (010-qemu-x86_64.mk:4).set -xeu, the --query preamble, a default for each QEMU_*_OPTION, then read -ra into an array, "$@" on the end, and exec.
#!/bin/bash and set -xeu (010-qemu.mk:57-59), so bash traces each command (-x), stops at the first failure (-e) and treats unset variables as errors (-u).--query block prints vm.memory_mb and the users, then exits (010-qemu.mk:63-92).default_qemu_*_option line per group, then : "${QEMU_X_OPTION:=$default…}", which keeps a value you set (010-qemu-x86_64.mk:62-80).read -ra splits each string into an array, the command is built as qemu_cmd, "$@" is appended (010-qemu-x86_64.mk:82-105), and exec "${qemu_cmd[@]}" replaces the script with QEMU (010-qemu-x86_64.mk:110-113).exec; see swtpm per launch.QEMU_MEM_OPTION="-m 4096" ./ubuntu-cloud-24.04.x86_64.run replaces the memory option. Arguments after the script name are appended to the QEMU command.
QEMU_ACCEL_MACHINE_PROP, QEMU_MEM_OPTION, QEMU_SMP_OPTION, QEMU_DISPLAY_OPTION, QEMU_BOOT_FIRMWARE_OPTION, QEMU_STORAGE_OPTION, QEMU_RNG_OPTION and QEMU_NET_OPTION, and QEMU_TPM_OPTION for the +tpm systems (010-qemu-x86_64.mk:72-80). Setting one replaces its whole group, so QEMU_BOOT_FIRMWARE_OPTION or QEMU_STORAGE_OPTION must name the files again.-m 2048 (010-qemu.mk:9, 010-qemu.mk:12); the display default is -nographic (010-qemu.mk:13); the RNG default is -device virtio-rng-pci (010-qemu.mk:45).QEMU_NET_OPTION, QEMU_STORAGE_OPTION, QEMU_TPM_OPTION and QEMU_ACCEL_MACHINE_PROP among them, and QEMU_NETDEV_USER_EXTRA, which is added to the default -netdev user option and which allocate sets to forward SSH; it suggests -display gtk (README.md:922-947). The man page describes each with its default (image-garden.1:610-679)."$@" is appended after every default (010-qemu-x86_64.mk:105). Whether a later option overrides an earlier one is up to QEMU.Run ./ubuntu-cloud-24.04.x86_64.run and log in at the prompt as ubuntu/ubuntu or root/root.
ubuntu/ubuntu or root/root (README.md:77-79).root with plain_text_passwd: root and a user named after the group, with the same password and sudo: ["ALL=(ALL) NOPASSWD:ALL"] (010-qemu.mk:200-214).ubuntu-24-04 here (010-qemu.mk:196).Changes go into ubuntu-cloud-24.04.x86_64.qcow2 and stay. With -snapshot they are thrown away when QEMU exits.
.run script to make each invocation ephemeral" (README.md:85-86).X.qcow2, the overlay that make prepared (rulegen.py:597-598); allocate runs the same script on the same file (image-garden:1153-1154), so a change made without -snapshot is in every machine allocated later (derived).-snapshot unless QEMU_SNAPSHOT_OPTION is set (image-garden:1154).X.qcow2 and make it again.Shut down from inside with sudo shutdown -h now. A machine started by its .run script has no SSH port; use image-garden allocate for that.
execs QEMU (010-qemu-x86_64.mk:110-113), so when the guest powers off and QEMU exits, nothing of the script is left running.QEMU_NETDEV_USER_EXTRA (image-garden:1107).Next: the serial console, image-garden allocate, and --query.
Read in the image-garden source at the commit in garden.commit ("code"); the values are the x86_64 EFI defaults. The README and the man page list the same variables (README.md:922-947, image-garden.1:610-679). Nothing was run for this page.
| Variable | Default | What it sets |
|---|---|---|
QEMU_ACCEL_MACHINE_PROP | ,accel=kvm:tcg when QEMU lists kvm, else ,accel=tcg | appended to -machine q35 |
QEMU_MEM_OPTION | -m 2048 | memory |
QEMU_SMP_OPTION | -smp 4 on an x86_64 host, -smp 1 elsewhere | CPUs |
QEMU_DISPLAY_OPTION | -nographic (allocate: -display none) | display and console |
QEMU_BOOT_FIRMWARE_OPTION | two -drive if=pflash lines: the read-only EFI code and the system's writable variable store | firmware |
QEMU_STORAGE_OPTION | -drive file=X.qcow2,…,cache=writeback,discard=unmap -device virtio-blk,…,bootindex=0 | the disk |
QEMU_RNG_OPTION | -device virtio-rng-pci | random numbers |
QEMU_NET_OPTION | -netdev user,id=netdev0… with virtio-net-pci | network |
QEMU_TPM_OPTION | +tpm systems only: -chardev socket…, -tpmdev emulator…, -device tpm-crb | TPM |
Sources: 010-qemu-x86_64.mk:4-11, 010-qemu-x86_64.mk:59-113, 010-qemu.mk:6-13, 010-qemu.mk:45, image-garden:1105. The SMP default is derived: mk/010-qemu-x86_64.mk sets QEMU_SMP_X86_64 = 1, and mk/010-qemu.mk, concatenated after it, sets the host architecture's variable to 4.
| Variable | Effect |
|---|---|
QEMU_NETDEV_USER_EXTRA | appended to -netdev user; allocate puts the SSH hostfwd here |
QEMU_SNAPSHOT_OPTION | read by allocate, not by the script: -snapshot unless set |
Everything after the script's name is appended to the QEMU command, after all the defaults. --query as the first argument prints facts about the system and exits instead.
ubuntu-core-24+tpm.x86_64.run starts swtpm on the state in ubuntu-core-24+tpm.x86_64.tpm/, then QEMU with a TPM device on swtpm's socket.
+tpm systems are ubuntu-core-24+tpm, 24+dangerous+tpm, 26+tpm and 26+dangerous+tpm, for x86_64 only; their keys are sealed to the TPM state in ubuntu-core-R.x86_64.tpm/, which "belongs with the disk image and the UEFI variables" (050-ubuntu-core.mk:9-16).EMIT_QEMU_SYSTEM_X86_64_EFI_RUN_COMMAND_WITH_TPM with the .tpm directory as its fifth argument (050-ubuntu-core.mk:63-68, 010-qemu-x86_64.mk:53-61).-chardev socket,id=chrtpm,path=SOCKET -tpmdev emulator,id=tpm0,chardev=chrtpm -device tpm-crb,tpmdev=tpm0 (010-qemu-x86_64.mk:132-133)..tpm/ directory together with the .qcow2 and .efi-vars.qcow2 files (README.md:711-718).Missing swtpm, another working directory, or a missing .tpm/ directory each stop the launcher with exit status 1 and a message.
command -v $(SWTPM), else "$0: swtpm, the TPM emulator, is required: install the swtpm package" and exit 1 (010-qemu-x86_64.mk:154-158, message 010-qemu-x86_64.mk:120).readlink -f "$0" and pwd -P, must be the current directory, else "$0: run this launcher from its own directory, DIR: its disk is sealed to the TPM state there" (010-qemu-x86_64.mk:159-167). The disk and the UEFI variables are named relative to it in the QEMU options (010-qemu-x86_64.mk:67-68).DIR/ubuntu-core-R.x86_64.tpm; without it: "$0: the TPM state, DIR, is missing: make the .qcow2 image again" (010-qemu-x86_64.mk:168-172).--query is answered before these checks, so it works without swtpm (010-qemu.mk:57-90).+tpm system without the swtpm component stops earlier, with "install the swtpm component to use systems with a TPM: snap install image-garden+swtpm" (010-qemu-x86_64.mk:124-131).The run directory is $GARDEN_TPM_RUN_DIR (allocate: port.PORT.tpm) or a new tpm.XXXXXXXX. With -snapshot swtpm gets a copy of the state in it.
GARDEN_TPM_RUN_DIR set the launcher runs mkdir -m 700 on it; otherwise it makes $XDG_RUNTIME_DIR/image-garden/tpm.XXXXXXXX with mktemp -d, or ${TMPDIR:-/tmp}/image-garden-tpm.XXXXXXXX without a runtime directory (010-qemu-x86_64.mk:173-189).$XDG_RUNTIME_DIR/snap.image-garden/image-garden, which the snap's confined swtpm and QEMU can reach (010-qemu-x86_64.mk:177-181).GARDEN_TPM_RUN_DIR=$XDG_RUNTIME_DIR/image-garden/port.PORT.tpm and removes a leftover one first (image-garden:825-831, image-garden:1108-1112).-snapshot "swtpm must not change the TPM state either: it gets a copy" (010-qemu-x86_64.mk:137-152). The copy is cp -a STATE RUN_DIR/state when any argument is -snapshot (010-qemu-x86_64.mk:190-197).-snapshot unless QEMU_SNAPSHOT_OPTION is set (image-garden:1154). Run without it, the launcher lets swtpm change the real state, as QEMU changes the real disk and variables.swtpm socket --tpm2 --tpmstate dir=… --ctrl type=unixio,path=…/swtpm.sock --pid file=… --terminate --daemon, a watcher, then QEMU with -tpmdev emulator and -device tpm-crb.
$(SWTPM) socket --tpm2 --tpmstate dir=STATE --ctrl type=unixio,path=RUN/swtpm.sock --pid file=RUN/swtpm.pid --terminate --daemon; if it fails, the run directory is removed and the launcher exits 1 (010-qemu-x86_64.mk:198-201).(tail --pid=SWTPM_PID -f /dev/null; rm -rf RUN) </dev/null >/dev/null 2>&1 &, so it also works when QEMU detaches with -daemonize (010-qemu-x86_64.mk:202-203, comment :151-152).QEMU_TPM_OPTION, default from QEMU_TPM_OPTION_FOR on the socket, and -global driver=cfi.pflash01,property=secure,value=on on the firmware flash (010-qemu-x86_64.mk:67, :71, :80, :104, :133-135).EMIT_SWTPM_RUN_QEMU runs QEMU without exec and, if it fails, kills swtpm and exits with QEMU's status (010-qemu-x86_64.mk:207-216).--terminate exits when its client disconnects is from swtpm's options as the comment describes them (010-qemu-x86_64.mk:140-142).QEMU exits, swtpm terminates, the watcher removes the run directory and the copied state. discard and the next allocate on the port remove it too.
discard_tpm_run_dir: waits up to 5 seconds while swtpm runs and is not a zombie, kills it, then retries rm -rf for 2 seconds because the watcher may remove the directory at the same time (image-garden:833-865). allocate calls it too when the machine dies before SSH or fails to start (image-garden:1186-1190, image-garden:1208-1210).rm -rf on port.PORT.tpm before it starts the launcher (image-garden:1108-1112).tpm.XXXXXXXX directory that only the watcher removes.EMIT_QEMU_SYSTEM_X86_64_EFI_RUN_COMMAND_WITH_TPM with $(5) set adds EMIT_SWTPM_START, QEMU_SECURE_PFLASH_OPTION, QEMU_TPM_OPTION_FOR and EMIT_SWTPM_RUN_QEMU; the +tpm rules set q35,smm=on.
EMIT_QEMU_SYSTEM_X86_64_EFI_RUN_COMMAND calls ..._WITH_TPM with an empty fifth argument (010-qemu-x86_64.mk:46-51); with a fifth argument the template adds EMIT_SWTPM_START, the secure pflash option, default_qemu_tpm_option, QEMU_TPM_OPTION and EMIT_SWTPM_RUN_QEMU instead of EMIT_EXEC_QEMU (010-qemu-x86_64.mk:53-113).+tpm rules: QEMU_SYSTEM_X86_64_MACHINE = q35,smm=on for their .run and .qcow2, Secure Boot firmware copies converted with $(QEMU_IMG) from efi-secboot-code.x86_64.img and efi-secboot-vars.x86_64.img, and the launcher with ubuntu-core-R.x86_64.tpm (050-ubuntu-core.mk:55-68).mkdir -m 700, starts swtpm on it in a tpm.XXXXXXXX run directory, boots with the seed, fails when the log says QEMU was stopped by a signal, then waits up to 10 s for swtpm and removes the run directory (050-ubuntu-core.mk:77-106).SWTPM is swtpm, or, in a launcher made by the snap and run outside it, image-garden.swtpm (010-qemu-x86_64.mk:115-119).+tpm qcow2 rule runs under bash with set -o pipefail, so a QEMU that fails gives the recipe its status through tee (050-ubuntu-core.mk:77-99); the Ubuntu Core rules without a TPM do the same (050-ubuntu-core.mk:37-53), and .DELETE_ON_ERROR removes the half-made disk (000-garden.mk:4-7).Next: the +tpm systems, discard, swtpm in the snap, and full-disk encryption on the snapd map.
Read in the image-garden source at the commit in garden.commit ("code"). Nothing was run: swtpm was not installed where this deck was written. What swtpm's own options do is taken from the comments in the code.
| Step | What | Source |
|---|---|---|
| 1 | --query: answer and exit | 010-qemu.mk:57-90 |
| 2 | swtpm on PATH, or exit 1 | 010-qemu-x86_64.mk:154-158 |
| 3 | run from the launcher's directory, or exit 1 | 010-qemu-x86_64.mk:159-167 |
| 4 | SYSTEM.x86_64.tpm/ exists, or exit 1 | 010-qemu-x86_64.mk:168-172 |
| 5 | run directory: GARDEN_TPM_RUN_DIR, or a new tpm.XXXXXXXX | 010-qemu-x86_64.mk:173-189 |
| 6 | with -snapshot: copy the state into RUN/state | 010-qemu-x86_64.mk:190-197 |
| 7 | swtpm socket … --terminate --daemon | 010-qemu-x86_64.mk:198-202 |
| 8 | the watcher, which removes the run directory when swtpm exits | 010-qemu-x86_64.mk:203 |
| 9 | QEMU with -machine q35,smm=on, secure pflash and a tpm-crb device; kill swtpm if it fails | 010-qemu-x86_64.mk:59-108, :207-216 |
| Path | What | Lifetime |
|---|---|---|
ubuntu-core-R.x86_64.tpm/ | the TPM state the disk keys are sealed to, next to the disk | made by the first boot, removed by clean |
$XDG_RUNTIME_DIR/image-garden/port.PORT.tpm/ | run directory of an allocated machine | until swtpm exits, discard, or the next allocate on the port |
$XDG_RUNTIME_DIR/image-garden/tpm.XXXXXXXX/ | run directory of any other launch | until swtpm exits |
RUN/swtpm.sock, RUN/swtpm.pid | swtpm's control socket and PID | with the run directory |
RUN/state/ | the copy used under -snapshot | with the run directory |
Sources: 050-ubuntu-core.mk:314-318, image-garden:825-865.
| Variable | Effect |
|---|---|
GARDEN_TPM_RUN_DIR | the run directory to create; allocate sets it |
XDG_RUNTIME_DIR | where run directories go; without it ${TMPDIR:-/tmp} |
QEMU_TPM_OPTION | replaces the TPM options of the launcher |
SWTPM (make) | the swtpm command written into the launcher |
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.
type: standard: spread, spread-plus, six qemu-<arch>, pkgproxy and swtpm (snapcraft.yaml:45-119).snap install image-garden+qemu-aarch64 as the manual way (README.md:309-320).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.
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).$SNAP/../components/$SNAP_REVISION/NAME, that is /snap/image-garden/components/REVISION/NAME (qemu-system-x86_64:9-36).snapctl install +NAME (install:13).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.Six qemu-arch components, pkgproxy, swtpm, spread and spread-plus. The snap itself keeps image-garden, qemu-img, the tools, virtiofsd and the stubs.
qemu-system-<arch>, the keymaps and the firmware files that architecture's machines load into each one; the snap itself keeps only qemu-img (snapcraft.yaml:327-429).qemu-x86-64 (snapcraft.yaml:645-665); Fedora's and Jammy's EDK2 builds for some aarch64 systems go into qemu-aarch64 (snapcraft.yaml:459-486).bin/pkgproxy and bin/pkgproxyctl (snapcraft.yaml:599-601); swtpm's holds bin/swtpm and its libraries (snapcraft.yaml:608-644).qemu-system-*, pkgproxy, pkgproxyctl, swtpm and virtiofsd (qemu-stubs/Makefile:10); spread's stand-in is spread-chooser (snapcraft.yaml:211-226). All but virtiofsd stand in for a program in a component.usr/libexec/virtiofsd from Ubuntu's virtiofsd package (snapcraft.yaml:602-607), and the image-garden.virtiofsd app runs it through its stub, which adds --sandbox none (snapcraft.yaml:140-148, virtiofsd:6-15).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.
snapctl install +qemu-$(uname -m) (with _ as -) +pkgproxy, unless the revision is a local one (install:6-14).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).+pkgproxy when pkgproxy is unset, true or component and the component is missing (post-refresh:9-29).snapctl install run from a hook (derived, overlord/hookstate/ctlcmd/helpers.go in snapd).snap set. So a store install ends with three components: the host's QEMU, pkgproxy and spread.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.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.
$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).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.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).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).A sideloaded revision (x1, x2…) installs no components. Install them from their files: snap install --dangerous ./image-garden+pkgproxy_*.comp.
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).--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).x1, x2 and so on, and has no store revision whose components could be fetched.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.snap connect for pkgproxy=snap).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.
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.
| 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.
| 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 |
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.
| 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 |
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).spread and spread-plus parts build each runner with Go and organize the binary into its component as spread (snapcraft.yaml:545-583).swtpm and ovmf-x86-64 parts stage Ubuntu packages, keep a few files in component/ and delete the rest (snapcraft.yaml:608-665).In snapshot mode the guest's writes go to a scratch file on the host. With the snap, it lives in ~/snap/image-garden/common/tmp, on disk, unless a fallback sends it to /tmp.
.run script with ${QEMU_SNAPSHOT_OPTION=-snapshot}, so every allocated machine runs in snapshot mode unless that variable is set (image-garden:1153-1163).$SNAP_USER_COMMON/tmp, and /tmp/./ only when that cannot be made (qemu-var-tmp:6-20).~/snap/image-garden/common/tmp (README.md:155-161).-snapshot keeps the image unchanged by writing the guest's changes to an overlay file in QEMU's temporary directory: $TMPDIR, or /var/tmp when that is unset or /tmp.
-snapshot unless QEMU_SNAPSHOT_OPTION is set, for example to the empty string (image-garden:1153-1163).-snapshot, QEMU opens each disk with a temporary qcow2 overlay of its own and deletes it when it exits. Writes go to that overlay; the image file is not modified.qemu-var-tmp sets TMPDIR=$SNAP_USER_COMMON/tmp, that is ~/snap/image-garden/common/tmp, when /var/tmp is not writable. Every -snapshot overlay grows there, on disk.
qemu-var-tmp touches /var/tmp/image-garden-canary. If that fails and SNAP_USER_COMMON is set and mkdir -p "$SNAP_USER_COMMON"/tmp succeeds, it exports TMPDIR="$SNAP_USER_COMMON"/tmp; otherwise it exports TMPDIR=/tmp/./. Then it execs the rest of the command chain (qemu-var-tmp:9-23). The slide's panel leaves out the then keywords and the error redirections.image-garden app and every qemu-system-* app list usr/bin/qemu-var-tmp in their command-chain (snapcraft.yaml:122-131, snapcraft.yaml:149-160); so does the spread app (snapcraft.yaml:211-226).~/snap/image-garden/common/tmp instead of its private /tmp, which is a tmpfs on many hosts" (README.md:155-161).$SNAP_USER_COMMON is ~/snap/image-garden/common for the user who runs the app, so /root/snap/image-garden/common/tmp for root, as under sudo or spread. /var/tmp is not writable under strict confinement (confinement: strict, snapcraft.yaml:43), which is why the canary fails there.If $SNAP_USER_COMMON/tmp cannot be made, TMPDIR=/tmp/./: the snap's private /tmp. On a tmpfs host the guest's writes then take RAM on top of -m.
SNAP_USER_COMMON is empty or mkdir -p "$SNAP_USER_COMMON"/tmp fails, the wrapper exports TMPDIR=/tmp/./; its comment says the path "is still /tmp but does not compare to /tmp exactly, which QEMU would replace with /var/tmp" (qemu-var-tmp:13-19). Nothing is printed when it falls back./tmp because it "is a tmpfs on many hosts", and that a scratch directory on tmpfs "would use RAM" allocate's memory check "does not see" (README.md:155-161)./tmp, a directory inside the host's /tmp. Where that is a tmpfs, files in it take RAM (and swap) until they are deleted. Derived as well: snapd always sets SNAP_USER_COMMON for an app, so the fallback needs a home directory where the directory cannot be made, for example one that is not writable.findmnt /tmp (util-linux) shows whether /tmp is a tmpfs.The memory check counts only -m. Four VMs that write 10 GB each need 40 GB free in ~/snap/image-garden/common/tmp (root's home under sudo). QEMU_SNAPSHOT_OPTION="" writes into the image: use a copy.
vm.memory_mb from .run --query and compares it with MemAvailable less a reserve (GARDEN_MEMORY_RESERVE), divided by 1.5; it knows nothing of disk writes (image-garden:711-782). The README: "allocate's memory check counts only the machine's memory (-m)" (README.md:155-161).$SNAP_USER_COMMON/tmp, so they take space on that file system until QEMU exits; df shows it even when the files have no name in the directory.$SNAP_USER_COMMON belongs to the user who runs the app: /root/snap/image-garden/common for root (derived, snapd's layout).QEMU_SNAPSHOT_OPTION; set to the empty string, allocate runs the machine without -snapshot and the guest writes into the system's .qcow2 (image-garden:1153-1163). Copy the .qcow2 (and, for UEFI systems, the .efi-vars.qcow2) first, or rebuild with make afterwards./var/tmp, holds the overlays there unless TMPDIR says otherwise (README.md:96-106 compares the installs).Plugs include home, not removable media. Without /run/user/UID, pid files and locks go to /run/snap.image-garden/image-garden/.
home, kvm, network, network-bind and pkgproxy-sockets (snapcraft.yaml:122-131); there is no removable-media plug, so paths outside the home directory, such as /srv, are not reachable. Derived from the plug list.XDG_RUNTIME_DIR to /run/user/UID/snap.NAME even where /run/user/UID does not exist, as for root under sudo or spread. The snap cannot create it, so image-garden uses /run/snap.$SNAP_INSTANCE_NAME (image-garden:64-73). allocate's pid files, locks and TPM run directories go under $XDG_RUNTIME_DIR/image-garden/.$SNAP_USER_COMMON/cache in the snap (image-garden:20-29).Launchers call image-garden.qemu-system-* and image-garden.swtpm; image-garden.virtiofsd runs with --sandbox none. docker comes from the docker snap through docker-executables. A sideloaded snap installs no components.
image-garden.qemu-system-x86-64 when run from outside the snap, and qemu-system-x86_64 inside it (010-qemu-x86_64.mk:4); the same holds for swtpm and image-garden.swtpm (010-qemu-x86_64.mk:115-119). The QEMU app starts through qemu-var-tmp too, so its overlay goes to $SNAP_USER_COMMON/tmp as well (snapcraft.yaml:149-160).virtiofsd app plugs home and network-bind (snapcraft.yaml:140-148). Its stub adds --sandbox none unless the caller passes a --sandbox option: virtiofsd's default sandbox "enters new namespaces, which strict confinement does not allow", and "the snap's confinement still limits what virtiofsd can reach" (virtiofsd:6-15). See sharing host directories.spread app plugs docker and docker-executables (snapcraft.yaml:211-226). The content plug mounts the docker snap's executables at $SNAP/docker-snap (snapcraft.yaml:267-270); the docker stub prints how to connect them when they are missing (docker:6-35).x1, x2…) (install:6); the configure hook does the same (configure:47-53).Next: the snap overview, allocate and its snapshot mode, the three ways to install, and sharing host directories with virtiofs.
/var/tmp; the wrapper sends QEMU's -snapshot overlays to ~/snap/image-garden/common/tmp, on disk, or to the snap's /tmp, which may be memory, when that directory cannot be made; allocate counts neither.Read in the snap's snapcraft.yaml, hooks and stubs, the README and the image-garden script at the commit this map describes ("code"). Statements about QEMU's -snapshot overlay, snapd's private /tmp, $SNAP_USER_COMMON and tmpfs are general behaviour, not image-garden's code ("derived").
| Limit | What you notice | What image-garden does | What you can do |
|---|---|---|---|
/var/tmp is not writable | QEMU's -snapshot overlays cannot go to /var/tmp | qemu-var-tmp sets TMPDIR=$SNAP_USER_COMMON/tmp, that is ~/snap/image-garden/common/tmp, on disk (qemu-var-tmp:9-23, README.md:155-161) | keep enough free space under your home (root's home under sudo or spread) |
$SNAP_USER_COMMON/tmp cannot be made | the overlays go to the snap's private /tmp; on a tmpfs host, write-heavy tests use host RAM far beyond -m | TMPDIR=/tmp/./, spelled so QEMU does not replace it (qemu-var-tmp:13-19) | make sure that directory exists and is writable; findmnt /tmp shows a tmpfs |
| allocate's memory check | the overlays are not counted, wherever they are | counts only -m (image-garden:711-782) | budget disk (or RAM) for what tests write; fewer parallel VMs; QEMU_SNAPSHOT_OPTION="" on a copy; or the container or a native install |
only home | projects outside your home directory are not reachable | plugs home, kvm, network, network-bind, pkgproxy-sockets (snapcraft.yaml:122-131) | keep projects under $HOME |
no /run/user/UID for root without a session | pid files would have nowhere to go | XDG_RUNTIME_DIR=/run/snap.image-garden (image-garden:64-73) | look in /run/snap.image-garden/image-garden/ |
| launchers run from a host shell | QEMU is still the snap's | launchers name image-garden.qemu-system-* and image-garden.swtpm (010-qemu-x86_64.mk:4, 010-qemu-x86_64.mk:115-119) | expect the same scratch directory |
| no docker inside the sandbox | spread's docker backend fails with a notice | docker stub, docker-executables content plug (docker:6-35) | snap connect image-garden:docker-executables docker:docker-executables and snap connect image-garden:docker docker:docker |
| a sideloaded snap has no store | components are not installed | hooks skip x revisions (install:6) | install the .comp files too, or the snap from the store |
| virtiofsd's own sandbox | its namespace sandbox is not allowed | the virtiofsd app's stub adds --sandbox none (virtiofsd:6-15); plugs home, network-bind (snapcraft.yaml:140-148) | share directories under your home |
| pkgproxy snap's sockets | pkgproxy=snap needs them | content plug pkgproxy-sockets (snapcraft.yaml:255-266) | snap connect image-garden:pkgproxy-sockets pkgproxy:sockets |
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.
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).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).snap install image-garden (README.md:132-137).qemu-patches/guestfwd-unix-socket.patch; see the guestfwd patch.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.
+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).+pkgproxy when the pkgproxy setting is unset, true or component and the component is missing (post-refresh:9-29).pkgproxy app, daemon: simple, restart-condition: always (snapcraft.yaml:227-246).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.
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.snap install image-garden+swtpm (README.md:326-334).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).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.
image-garden app plugs kvm, home, network, network-bind and pkgproxy-sockets (snapcraft.yaml:122-131).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).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).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).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).Downloads: ~/snap/image-garden/common/cache/dl. Prepared images: your project or .image-garden/. pkgproxy: /var/snap/image-garden/common/cache/pkgproxy.
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).-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).Next: image-garden make, the components, the pkgproxy setting, spread, swtpm, confinement, and the comparison of the three installs.
snap install image-garden, then image-garden make ubuntu-cloud-24.04.x86_64.run, then ./ubuntu-cloud-24.04.x86_64.run.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.
| 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) |
| 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.
| 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).
| 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 |
snap set image-garden pkgproxy= takes component (the default), snap, http://host[:port] or none.
snap set image-garden pkgproxy=component (the default), =snap, =http://pkgproxy.example.lan:3142 and =none (README.md:211-221).none exists mainly for cases like snapd.git's spread suite, where some tests aren't yet adjusted for the injected SNAPPY_FORCE_API_URL environment variable or the extra /etc/hosts entries" (proxy/README.md:132-136).true means component and false means none (configure:18-24).The hook checks the value, starts or stops image-garden.pkgproxy, and writes pkgproxy-mode and pkgproxy-url in /var/snap/image-garden/common for make.
snapctl get pkgproxy and mapped to a mode: component, none, snap or external (configure:17-39). A URL must match ^http://[A-Za-z0-9.-]+(:[0-9]+)?/?$; anything else exits 1 with pkgproxy must be component, snap, none or a URL such as http://192.0.2.1:3142, which fails the snap set (derived: a failing configure hook fails the change).component runs snapctl start --enable image-garden.pkgproxy; every other mode runs snapctl stop --disable and removes pkgproxy.sock, stats.sock and pkgproxy-lxd-tls.sock (configure:6-9, configure:41-74).$SNAP_COMMON/pkgproxy-mode, and $SNAP_COMMON/pkgproxy-url for a URL (without a trailing slash) or removes it (configure:76-81). make reads both at every run (010-qemu.mk:20-23).spread-variant; see choosing a spread.image-garden.pkgproxy listens on pkgproxy.sock and caches in /var/snap/image-garden/common/cache/pkgproxy. snap logs image-garden.pkgproxy, image-garden.pkgproxyctl stats.
pkgproxy -addr pkgproxy:3142 -socket-path $SNAP_COMMON/pkgproxy.sock -cache-dir $SNAP_COMMON/cache/pkgproxy -lxd-tls-socket-path $SNAP_COMMON/pkgproxy-lxd-tls.sock, daemon: simple, restart-condition: always (snapcraft.yaml:227-246). Its stats socket defaults to $SNAP_COMMON/stats.sock (snapcraft.yaml:228-231).apt, snap and go; logs go to the journal (snap logs image-garden.pkgproxy); "there is no mechanism to reclaim used storage" (proxy/README.md:138-143).image-garden.pkgproxyctl stats prints per-snap download, hit and revision counts and bandwidth saved, and the apt packages saving the most; -json and -limit N change the output (proxy/README.md:206-217).component or true with the component missing, the hook runs snapctl install +pkgproxy, or prints cannot install the pkgproxy component: snap install image-garden+pkgproxy; it does not do so for an unset value, during the snap's own install (configure:41-53).$SNAP_COMMON is /var/snap/image-garden/common, one directory for the whole machine, kept across revisions.snap connect image-garden:pkgproxy-sockets pkgproxy:sockets, then snap set image-garden pkgproxy=snap. The sockets appear in $SNAP_COMMON/pkgproxy-host-snap/sockets.
interface: content, content: pkgproxy-sockets, target: $SNAP_COMMON/pkgproxy-host-snap; snapd mounts the pkgproxy snap's sockets slot (its $SNAP_COMMON/sockets) at $SNAP_COMMON/pkgproxy-host-snap/sockets. The comment there says snapd auto-connects it for two store snaps of the same publisher, and a sideloaded snap needs snap connect image-garden:pkgproxy-sockets pkgproxy:sockets (snapcraft.yaml:254-266).snap, make looks for the sockets in that directory and bridges them exactly as for the bundled pkgproxy (010-qemu.mk:22-23, proxy/README.md:112-115).snap: exit 1 with pkgproxy=snap needs the pkgproxy snap's sockets: snap connect image-garden:pkgproxy-sockets pkgproxy:sockets. Accepted: the bundled service is stopped and disabled (configure:56-70).Disconnecting pkgproxy-sockets sets pkgproxy=component and applies it. A mode that already was snap only warns when the plug is missing.
disconnect-plug-pkgproxy-sockets hook: with pkgproxy set to snap, it prints The pkgproxy snap's sockets are disconnected: setting pkgproxy=component, the bundled pkgproxy, runs snapctl set pkgproxy=component and then execs the configure hook, because "a snapctl set in this hook does not run the configure hook" (disconnect-plug-pkgproxy-sockets:6-15).snap and the plug is not connected, the configure hook prints pkgproxy=snap, but the pkgproxy snap's sockets are not connected: guests get no pkgproxy until snap connect image-garden:pkgproxy-sockets pkgproxy:sockets and carries on, so a refresh or another snap set does not fail (configure:57-68).snap mode keep the bridge to pkgproxy-host-snap/sockets in their .run script; see no rebuild.pkgproxy=http://pkgproxy.example.lan:3142 or pkgproxy=none. Downloads follow the setting; systems made earlier keep the old one until made again.
http://host[:port], port 80 when none is given; the hook checks the form, stops the bundled service and saves the URL (configure:28-33, configure:71-80). make resolves the host with getent ahostsv4 when it makes a system's files, and warns cannot use pkgproxy at "URL": want http://host[:port] with a host that resolves to IPv4; guests get no pkgproxy when it cannot (010-qemu.mk:24-29).none or false: the service is stopped and disabled, its sockets removed (configure:71-73).PKGPROXY_URL or GARDEN_DL_PKGPROXY is set (README.md:273-278).Next: how a guest reaches pkgproxy, why nothing is rebuilt, the components, the GitHub action and image downloads.
Read in the snap's hooks, snap/snapcraft.yaml, mk/010-qemu.mk and proxy/README.md of image-garden v0.8.0 ("code"). That a failing configure hook fails snap set, and where $SNAP_COMMON is, are snapd's behaviour ("derived"). Nothing was run for this page.
snap set image-garden pkgproxy=VALUE is handled by the configure hook (configure:11-39).
| Value | Mode | Who answers the guests | What the hook does |
|---|---|---|---|
unset, true, component | component (the default) | the bundled pkgproxy daemon, image-garden.pkgproxy | installs the pkgproxy component when it is missing after a refresh in another mode, then starts and enables the daemon (configure:41-55) |
snap | snap | the separate pkgproxy snap, through its sockets | needs snap connect image-garden:pkgproxy-sockets pkgproxy:sockets; refuses to switch without it; stops the bundled daemon (configure:56-70) |
http://host[:port] | external | a pkgproxy elsewhere | checks the URL's form, stops the bundled daemon, saves the URL (configure:28-33) |
none, false | none | nobody | stops the bundled daemon and removes its sockets (configure:6-9) |
The hook writes the mode to $SNAP_COMMON/pkgproxy-mode and, for a URL, the URL to $SNAP_COMMON/pkgproxy-url (configure:76-82); mk/010-qemu.mk reads both when it makes the user-data and the .run script (010-qemu.mk:20-44).
Disconnecting pkgproxy-sockets, as removing the pkgproxy snap does, sets pkgproxy=component and runs the configure hook again, so guests go back to the bundled pkgproxy (disconnect-plug-pkgproxy-sockets:6-15).
.run scripts made earlier keep the pkgproxy they were made with: see no rebuild.10.0.2.100:3142 through QEMU's guestfwd; with a URL, at that address: see reaching the host.GARDEN_DL_PKGPROXY says otherwise: see image downloads.| When | Message | Source |
|---|---|---|
snap set with a value of another form | pkgproxy must be component, snap, none or a URL such as http://192.0.2.1:3142 | configure:28-38 |
pkgproxy=snap without the plug connected | pkgproxy=snap needs the pkgproxy snap's sockets: snap connect image-garden:pkgproxy-sockets pkgproxy:sockets | configure:63-66 |
a refresh or snap set with the mode already snap and the plug missing (a warning) | pkgproxy=snap, but the pkgproxy snap's sockets are not connected: guests get no pkgproxy until snap connect … | configure:67 |
| the pkgproxy snap's sockets disconnected | The pkgproxy snap's sockets are disconnected: setting pkgproxy=component, the bundled pkgproxy | disconnect-plug-pkgproxy-sockets:11-14 |
component set again, the component cannot be installed | cannot install the pkgproxy component: snap install image-garden+pkgproxy | configure:48-53 |
| make, a URL that does not resolve | cannot use pkgproxy at "URL": want http://host[:port] with a host that resolves to IPv4; guests get no pkgproxy | 010-qemu.mk:29 |
| File | Written by | What |
|---|---|---|
pkgproxy-mode | the configure hook | component, snap, external or none |
pkgproxy-url | the configure hook, URL mode only | the URL, without a trailing slash |
pkgproxy.sock, pkgproxy-lxd-tls.sock, stats.sock | the bundled service | removed when another mode is chosen |
cache/pkgproxy/ | the bundled service | its cache: apt, snap, go |
pkgproxy-host-snap/sockets/ | snapd, through the pkgproxy-sockets plug | the pkgproxy snap's sockets, in snap mode |
The spread and spread-plus components, one app: image-garden.spread. snap alias image-garden.spread spread gives it the plain name.
spread, "Spread integration test runner", and spread-plus, "a fork of Spread with additional features and fixes", each pinned to a Git revision (snapcraft.yaml:46-58). spread-plus comes from github.com/canonical/spread-plus (snapcraft.yaml:564-583).spread app runs usr/bin/spread-chooser through qemu-var-tmp, sets SPREAD_HOST_PATH: $PATH and plugs kvm, home, network, network-bind, pkgproxy-sockets, docker and docker-executables (snapcraft.yaml:211-226).snap alias image-garden.spread spread (action.yaml:394-397).# spread-variant=plus in ./spread.yaml, else snap get image-garden spread-variant, else plain spread. The chooser execs components/REVISION/spread-plus/spread with your arguments.
spread-chooser reads spread.yaml in the current directory only, takes the first line matching ^\s*#\s*spread-variant= and strips the prefix and trailing blanks (spread-chooser:5-9).snapctl get spread-variant (spread-chooser:51-54).spread-V, without one the component spread (spread-chooser:56-59), by exec'ing $SNAP/../components/$SNAP_REVISION/COMPONENT/spread "$@" (spread-chooser:38-49); a missing component is the next scene. Both components name their binary spread (snapcraft.yaml:561, snapcraft.yaml:581).sudo snap set image-garden spread-variant=plus installs spread-plus through the configure hook. The chooser installs a missing component only as root; otherwise it shows snap install image-garden+spread-plus and exits 1.
snapctl get spread-variant: empty, it runs snapctl install +spread when components/REVISION/spread/spread is not executable; a valid variant V, snapctl install +spread-V when components/REVISION/spread-V/spread is not; both only for a store revision (configure:83-107).image-garden+spread "as it is installed: its configure hook runs as root then", and snap set image-garden spread-variant=plus installs another variant (README.md:163-179). Derived, from snapd: the configure hook runs at install, at refresh and after snap set.spread is not executable, runs snapctl install "+COMPONENT" only when id -u is 0, ignoring its failure; if spread is still missing it shows a message headed Notice, "It seems that the component COMPONENT is not installed", "The image-garden snap requires the component COMPONENT in order to run spread.", then "Install the component with the following command: snap install image-garden+COMPONENT", and exits 1 (spread-chooser:11-49). The README says the same (README.md:184-187).overlord/hookstate/ctlcmd/ctlcmd.go): install is not among the snapctl commands a user other than root may run, which is why the chooser does not try it then.snap set when its spread-variant input is set (action.yaml:398-401).Projects under $HOME. SPREAD_HOST_PATH carries your PATH to the backend's hooks. docker and docker-executables plugs for the docker backend.
home, and no removable-media (snapcraft.yaml:219-226).SPREAD_HOST_PATH: $PATH (snapcraft.yaml:215-218). image-garden's own spread.yaml restores it in its allocate and discard (spread.yaml:27-35).docker-executables content plug mounts the docker snap's executables at $SNAP/docker-snap; the docker stub runs $SNAP/docker-snap/bin/docker or prints how to connect image-garden:docker-executables docker:docker-executables and image-garden:docker docker:docker (snapcraft.yaml:267-270, docker:6-35).qemu-var-tmp, so its temporary directory follows the same rule as QEMU's (snapcraft.yaml:212-214).Only ./spread.yaml is read. A setting that is not a valid component name fails snap set. An unknown variant has no component. A sideloaded snap needs snap install --dangerous ./image-garden+spread_*.comp.
spread.yaml in the current directory is read (spread-chooser:5-9). Whether spread itself accepts .spread.yaml or looks in other directories is spread's own behaviour, not in this tree.*[!a-z0-9-]*, [!a-z]*, *- or *--*, that is anything but lowercase ASCII letters, digits and single dashes, starting with a letter and not ending with a dash: the rules of component names, since the variant names the component spread-VARIANT. It exits 1 with spread-variant must start with a lowercase ASCII letter and may only use lowercase ASCII letters, digits and single dashes, not at the end, and installs nothing (configure:94-99). A one-letter name such as p is accepted.snap set fail, so the setting is not stored.pluss, makes the hook run snapctl install +spread-pluss (configure:100-106), which snapd refuses because the snap has no such component (derived); the hook then fails, and so does snap set..comp files are built next to the snap (README.md:228-232).Next: testing with spread, the allocate and discard hooks, the GitHub action, the components and spread on GitLab.
Read in the image-garden source at the commit this map describes ("code"): spread-chooser/spread-chooser, snap/hooks/configure and snap/snapcraft.yaml. When snapd runs the configure hook and who may run snapctl install come from snapd's source ("derived"). Nothing was run for this page.
| Order | Source | Example | Component |
|---|---|---|---|
| 1 | the first # spread-variant=V line in ./spread.yaml | # spread-variant=plus | spread-plus |
| 2 | the snap setting | snap set image-garden spread-variant=plus | spread-plus |
| 3 | neither | spread |
The chooser execs $SNAP/../components/$SNAP_REVISION/spread[-V]/spread with all its arguments (spread-chooser:5-59). The README documents the order (README.md:163-187).
| Who | When | What |
|---|---|---|
| the configure hook | install, refresh, every snap set (derived) | +spread with the setting empty, +spread-V with spread-variant=V, if missing; not for a sideloaded revision (configure:83-107) |
spread-chooser | each run as root, if the chosen component is missing | snapctl install +spread[-V], which snapd allows only for root; as any other user it does not try, and shows how to install it (spread-chooser:35-49) |
| you | any time | sudo snap install image-garden+spread-plus, or snap install --dangerous with the .comp file for a sideloaded snap |
| When | Message |
|---|---|
a spread-variant that is not a valid component name (lowercase letters, digits and single dashes, starting with a letter, not ending with a dash) | spread-variant must start with a lowercase ASCII letter and may only use lowercase ASCII letters, digits and single dashes, not at the end (configure:94-99) |
| the configure hook installing | Installing component with spread... or Installing component with spread variant (spread-V)... (configure:88, configure:103) |
| the chosen component missing, and not installed by the chooser | a message headed Notice: It seems that the component spread-plus is not installed. and The image-garden snap requires the component spread-plus in order to run spread., then Install the component with the following command: and snap install image-garden+spread-plus; exit 1 (spread-chooser:11-33) |
The Secure Boot firmware comes with qemu-x86-64. swtpm is its own component: snap install image-garden+swtpm.
qemu-x86-64 "contains the 64-bit x86 system emulator (QEMU) as well as the corresponding EFI firmware (EDK2) and the Secure Boot EFI firmware of Ubuntu (OVMF)" (snapcraft.yaml:59-66); the install hook installs it on x86_64 hosts (install:6-14).swtpm: "the TPM emulator behind the virtual TPM of the Ubuntu Core +tpm systems, which also need the qemu-x86-64 component. Other systems do not need it" (snapcraft.yaml:109-119). "It is not installed automatically: snap install image-garden+swtpm" (README.md:322-334).qemu-x86-64, the image-garden.swtpm app, and swtpm as a separate component (NEWS.snappy:26-30).OVMF_CODE_4M.secboot.fd and OVMF_VARS_4M.ms.fd in qemu-x86-64/share/ovmf, after the host's pair; copied to efi-secboot-code.x86_64.img and efi-secboot-vars.x86_64.img.
ovmf-x86-64 part stages Ubuntu's ovmf-generic package, keeps OVMF_CODE_4M.secboot.fd and OVMF_VARS_4M.ms.fd ("OVMF_VARS_4M.ms.fd is for the Secure Boot code") and its copyright file, and organizes them into (component/qemu-x86-64)/share/ovmf (snapcraft.yaml:645-665)./usr/share/OVMF/OVMF_CODE_4M.secboot.fd with /usr/share/OVMF/OVMF_VARS_4M.ms.fd first, the component's pair second; the Nth entries go together and the first pair where both exist wins (010-qemu-x86_64.mk:282-296).efi-secboot-code.x86_64.img and efi-secboot-vars.x86_64.img, after check-qemu-x86-64-component (010-qemu-x86_64.mk:298-308); each +tpm system converts them to its own .efi-code.qcow2 and .efi-vars.qcow2 (050-ubuntu-core.mk:57-61).please install x86_64 edk2 firmware with Secure Boot and Microsoft keys (the ovmf package) - not in … with … (010-qemu-x86_64.mk:300-308).bin/swtpm and lib/swtpm/ (libtpms, libswtpm_libtpms, json-glib), versioned from Ubuntu's package. The stub sets LD_LIBRARY_PATH.
swtpm part stages Ubuntu's swtpm package, unpinned, and keeps bin/swtpm, the libraries libswtpm_libtpms.so.0*, libtpms.so.0* and libjson-glib-1.0.so.0* in lib/swtpm, and the copyright files; everything else is deleted (snapcraft.yaml:608-644).changelog.Debian.gz, without the epoch; the build fails if it cannot be found (snapcraft.yaml:621-632).lib/swtpm to LD_LIBRARY_PATH and execs bin/swtpm (swtpm:34-39).install the swtpm component to use systems with a TPM: snap install image-garden+swtpm, before any download. A missing qemu-x86-64 is reported before the firmware is copied.
check-swtpm-component runs only in the snap and fails with install the swtpm component to use systems with a TPM: snap install image-garden+swtpm (010-qemu-x86_64.mk:121-131).ubuntu-core-24+tpm.x86_64.qcow2 to ubuntu-core-24-amd64.qcow2 for example, with check-swtpm-component as its first order-only prerequisite, so make stops before the download; the .qcow2 rule has it too (050-ubuntu-core.mk:74-79, 050-ubuntu-core.mk:279-289).snap install image-garden+swtpm and exits 1 when the component is missing (swtpm:11-32).check-qemu-x86-64-component: install qemu-x86-64 component to use x86_64 emulation (010-qemu-x86_64.mk:298, 010-qemu-x86_64.mk:310-316, 010-qemu.mk:50-55).Outside the snap the launcher runs image-garden.swtpm and image-garden.qemu-system-x86-64, with swtpm's socket in $XDG_RUNTIME_DIR/snap.image-garden/image-garden/.
SWTPM in a launcher made by the snap is a shell expression: image-garden.swtpm when SNAP_INSTANCE_NAME is unset at run time, swtpm inside the snap (010-qemu-x86_64.mk:115-119); QEMU is chosen the same way, image-garden.qemu-system-x86-64 or qemu-system-x86_64 (010-qemu-x86_64.mk:4).${XDG_RUNTIME_DIR:-/run/user/UID}/snap.image-garden/image-garden: "Outside the snap its confined swtpm and QEMU reach only the runtime directory of the snap" (010-qemu-x86_64.mk:173-189). Under allocate, GARDEN_TPM_RUN_DIR names the directory instead.swtpm app: command: usr/bin/swtpm, plugs home and network-bind ("Binding swtpm's UNIX sockets needs it") (snapcraft.yaml:132-139).Next: the +tpm systems, each launch of swtpm, the firmware search, the components, confinement, and the snapd map's encryption deck.
Read in the image-garden source at release v0.8.0 ("code"): snap/snapcraft.yaml, qemu-stubs/swtpm, mk/010-qemu-x86_64.mk and mk/050-ubuntu-core.mk. Nothing was run for this page; swtpm was not installed.
| Piece | Where in the snap | From | Installed |
|---|---|---|---|
OVMF_CODE_4M.secboot.fd, OVMF_VARS_4M.ms.fd | qemu-x86-64 component, share/ovmf/ | Ubuntu's ovmf-generic | with qemu-x86-64, by the install hook on x86_64 hosts |
swtpm and lib/swtpm/ | swtpm component | Ubuntu's swtpm | by you: snap install image-garden+swtpm |
usr/bin/swtpm stub | the snap | qemu-stubs/swtpm | always |
image-garden.swtpm app | the snap | runs the stub | always; plugs home, network-bind |
Sources: snapcraft.yaml:109-139, snapcraft.yaml:608-665, swtpm:6-39.
| Launcher run | swtpm | QEMU | swtpm's run directory |
|---|---|---|---|
inside the snap (image-garden allocate, image-garden make) | swtpm (the stub) | qemu-system-x86_64 (the stub) | GARDEN_TPM_RUN_DIR, or $XDG_RUNTIME_DIR/image-garden/tpm.XXXXXXXX |
| from a host shell | image-garden.swtpm | image-garden.qemu-system-x86-64 | ${XDG_RUNTIME_DIR:-/run/user/UID}/snap.image-garden/image-garden/tpm.XXXXXXXX |
Sources: 010-qemu-x86_64.mk:4, 010-qemu-x86_64.mk:115-119, 010-qemu-x86_64.mk:173-189.
| When | Message |
|---|---|
| make of a +tpm system without the swtpm component | install the swtpm component to use systems with a TPM: snap install image-garden+swtpm |
| make without the qemu-x86-64 component | install qemu-x86-64 component to use x86_64 emulation |
| make without any Secure Boot pair | please install x86_64 edk2 firmware with Secure Boot and Microsoft keys (the ovmf package) - not in … with … |
| the swtpm stub without its component | a message headed Notice, then snap install image-garden+swtpm |
| a launcher that finds no swtpm command | swtpm, the TPM emulator, is required: install the swtpm package |
Advanced. When a test touches a small part of a large data set, share the host directory instead of copying it in: the guest reads only what it opens.
image-garden.virtiofsd app, as "very efficient host-to-guest file system sharing", "useful for CI systems with native cache directories (e.g., GitHub Actions cache)", letting guests "directly access host caches without copying data" (README.md:280-290).Copying costs time in proportion to the whole data set; sharing, in proportion to what the test reads. virtiofs is fast; 9p is simpler.
image-garden.virtiofsd app (snapcraft.yaml:140-148), and lists it in its description (snapcraft.yaml:38). QEMU in the snap is built with --enable-virtfs, which gives 9p (snapcraft.yaml:357).virtiofsd serves a host directory over a unix socket; QEMU adds vhost-user-fs-pci with a tag; the guest runs mount -t virtiofs data /mnt.
usr/libexec/virtiofsd from the distribution's virtiofsd package (snapcraft.yaml:602-607); QEMU is built with --enable-vhost-user (snapcraft.yaml:356), which vhost-user-fs-pci needs.--socket-path=SOCKET --shared-dir=DIR; QEMU takes -chardev socket,id=fs0,path=SOCKET -device vhost-user-fs-pci,chardev=fs0,tag=data; the guest runs mount -t virtiofs data /mnt. The names vfsd.sock, fs0, data and ~/data are examples. In the snap, virtiofsd runs as the image-garden.virtiofsd app (snapcraft.yaml:140-148); see running virtiofsd from the snap.virtiofs needs guest memory shared with virtiofsd: -object memory-backend-memfd,id=mem,size=2G,share=on -numa node,memdev=mem, with the same size as -m. All of it fits in QEMU_MEM_OPTION.
-m 2048 (MiB) (010-qemu.mk:9, 010-qemu.mk:12). The .run script puts it in QEMU_MEM_OPTION unless already set (010-qemu-x86_64.mk:64, 010-qemu-x86_64.mk:73), splits it with read -ra (010-qemu-x86_64.mk:84) and passes the words to QEMU (010-qemu-x86_64.mk:97). So several options can share the one variable.-object memory-backend-memfd,id=mem,size=2G,share=on -numa node,memdev=mem, with size equal to -m.QEMU_MEM_OPTION="-m 2G -object memory-backend-memfd,id=mem,size=2G,share=on -numa node,memdev=mem" ./ubuntu-cloud-24.04.x86_64.run …One option, -virtfs local,path=DIR,mount_tag=data,security_model=none,readonly=on; in the guest, mount -t 9p -o trans=virtio,version=9p2000.L data /mnt. No daemon, but slower with many small files.
--enable-virtfs (snapcraft.yaml:357), and so is the container's (Dockerfile:51). The README lists virtfs among the snap's and the container's QEMU features (README.md:153, README.md:358). A distribution QEMU may or may not have it.-virtfs local,path=DIR,mount_tag=TAG,security_model=none|mapped-xattr|passthrough[,readonly=on] (or the longer -fsdev with -device virtio-9p-pci); in the guest mount -t 9p -o trans=virtio,version=9p2000.L TAG /mnt, with the guest's 9p modules.-snapshot protects the disk image, not a shared directory. A guest's writes reach the host directory: share it read-only when the test only reads.
.run script with ${QEMU_SNAPSHOT_OPTION=-snapshot} (image-garden:1154). -snapshot applies to the disk drives, here the system's .qcow2 (010-qemu-x86_64.mk:101).-snapshot does not cover a 9p or virtiofs share; readonly=on (9p) or a read-only mount makes the guest's writes fail. virtiofsd can also be started on a read-only bind mount of the directory.image-garden.virtiofsd --socket-path=$HOME/snap/image-garden/common/cache.sock --shared-dir=$HOME/cache &. The app adds --sandbox none unless you pass --sandbox; it reaches your home.
virtiofsd app runs usr/bin/virtiofsd, a stub, and plugs home, "for the shared directory", and network-bind, for "the vhost-user UNIX socket" (snapcraft.yaml:140-148).qemu-stubs/virtiofsd: "Its default sandbox enters new namespaces, which strict confinement does not allow, so the app runs without one unless the caller chooses another with --sandbox. The snap's confinement still limits what virtiofsd can reach: the home interface, the user's own files." It prepends --sandbox none when no argument starts with --sandbox, then execs $SNAP/usr/libexec/virtiofsd (virtiofsd:6-15).virtiofsd package into the snap, not into a component (snapcraft.yaml:602-607).--version, serves ~/shared on ~/snap/image-garden/common/virtiofsd.sock and waits for "Waiting for vhost-user socket connection"; no guest connects (tests/snap/virtiofsd/task.yaml). So a guest mounting a share through the snap was not tested there, nor for this map.--socket-path and --shared-dir are virtiofsd's own options (derived, from its documentation).Extra arguments to X.run, or after the system name in image-garden allocate, go to QEMU: the shared memory backend, -chardev socket,… and -device vhost-user-fs-pci,…,tag=cache. In the guest, mount -t virtiofs cache /mnt.
.run script appends "$@" to the QEMU command (010-qemu-x86_64.mk:105).image-garden allocate [--spread] [-p PORT] SYSTEM.ARCH [QEMU-OPTION...] (image-garden:1037); the options after the system name reach the .run script (image-garden:1160).debian-cloud-13.x86_64.run: start image-garden.virtiofsd with the socket in $HOME/snap/image-garden/common, then pass -object memory-backend-memfd,id=mem,size=2048M,share=on -numa node,memdev=mem, -chardev socket,id=cache,path=…/cache.sock and -device vhost-user-fs-pci,chardev=cache,tag=cache to the .run script, and in the guest mount -t virtiofs cache /mnt. The backend's size is the machine's memory, "2048M unless QEMU_MEM_OPTION says otherwise" (README.md:292-307, 010-qemu.mk:9). The slide uses the running example instead.Next: the .run script and allocate for passing options, caching on GitHub, and the snap and its confinement.
What image-garden provides (virtiofsd in the snap and its image-garden.virtiofsd app, virtfs in the snap's and the container's QEMU, the .run script's QEMU_MEM_OPTION and "$@", allocate's extra options) is read in image-garden at the commit this map describes ("code"); the virtiofs example follows the README's. The QEMU and virtiofsd options and the performance comparison are derived from their documented behaviour; the example command lines are illustrative and were not run for this map.
| virtiofs | 9p (virtfs) | |
|---|---|---|
| Where it comes from | virtiofsd, bundled in the snap and run as image-garden.virtiofsd, with --sandbox none (snapcraft.yaml:140-148, virtiofsd:6-15) | built into the snap's and the container's QEMU |
| Setup steps | start virtiofsd; add a chardev and a vhost-user-fs-pci device; shared memory; mount | one -virtfs option; mount |
| Daemon | yes: start before QEMU, stop after | no |
| Memory | guest RAM from a shared memory-backend-memfd, same size as -m | nothing special |
| Performance | close to native | slower, most for many small files and directory walks |
| Guest kernel | virtiofs file system | 9p and 9pnet_virtio |
| Read-only | a read-only mount, or serve a read-only directory | readonly=on |
| Typical use | large caches and trees read by many tests | a quick share, a few files, little metadata work |
After the README's example (README.md:292-307). On the host, start the daemon in the background:
image-garden.virtiofsd --socket-path="$HOME"/snap/image-garden/common/cache.sock \ --shared-dir="$HOME"/cache &
Then start the system with shared memory, as big as the machine's (-m 2048 unless QEMU_MEM_OPTION says otherwise), and the device:
./ubuntu-cloud-24.04.x86_64.run \ -object memory-backend-memfd,id=mem,size=2048M,share=on -numa node,memdev=mem \ -chardev socket,id=cache,path="$HOME"/snap/image-garden/common/cache.sock \ -device vhost-user-fs-pci,chardev=cache,tag=cache
In the guest:
mount -t virtiofs cache /mnt
./ubuntu-cloud-24.04.x86_64.run \ -virtfs local,path=$HOME/cache,mount_tag=data,security_model=none,readonly=on
In the guest:
mount -t 9p -o trans=virtio,version=9p2000.L data /mnt
Options after the system name go to the .run script:
image-garden allocate ubuntu-cloud-24.04.x86_64 \ -virtfs local,path=$HOME/cache,mount_tag=data,security_model=none,readonly=on
allocate runs the machine with -snapshot, which does not cover the shared directory: share read-only when the tests only read.
home interface covers your home directory).~/snap/image-garden/common, where both the virtiofsd app and the snap's QEMU reach it, as the README does.--sandbox yourself to choose another, which confinement may refuse.The garden backend is type: adhoc: two shell hooks, allocate and discard, and a list of systems.
garden: with type: adhoc, an allocate: | and a discard: | script and systems: (spread.yaml:24-72).exec image-garden allocate --spread "$SYSTEM"."$ARCH": --spread prints <ADDRESS localhost:PORT> or <FATAL …>, and exec hands the output and exit status to spread.
exec image-garden allocate --spread "$SYSTEM"."$ARCH", after ARCH="${ARCH:-$(uname -m)}" (spread.yaml:43-47).--spread sets the spread output mode (image-garden:1023-1024, image-garden:1114-1116); in that mode allocate prints <ADDRESS localhost:PORT> (image-garden:1203) or <FATAL …> and exits 213 (image-garden:1181-1190).exec keyword allows image-garden to handle the equivalent of spread shell functions like ADDRESS, FATAL, or ERROR. Use --spread to opt into that output mode explicitly." (README.md:755-756).--spread, allocate guesses from its parent processes whether spread called it, and prints a plain localhost:PORT otherwise (image-garden:1117-1147).In spread mode allocate waits for the SSH- banner, up to GARDEN_SSH_WAIT_TIMEOUT (600 seconds), before it prints the address.
SSH- banner until GARDEN_SSH_WAIT_TIMEOUT (default 600 seconds) runs out; at the deadline it prints the address anyway (image-garden:1172-1201).<FATAL SYSTEM exited before SSH became available, see SYSTEM.PORT.serial.log> and exits 213 (image-garden:1185-1190).QEMU_MEM_OPTION and QEMU_SMP_OPTION size the machine. From the snap, restore PATH from SPREAD_HOST_PATH in both hooks.
export QEMU_MEM_OPTION="-m ${SPREAD_QEMU_MEM:-4096}" and, when set, QEMU_SMP_OPTION="-smp $SPREAD_QEMU_SMP" (spread.yaml:37-42). The demo uses -smp 2 and 1024 MB, 2048 MB for Ubuntu Core (spread-demo/spread.yaml:18-23).PATH from SPREAD_HOST_PATH (spread.yaml:27-35, spread.yaml:49-57).spread app sets SPREAD_HOST_PATH: $PATH (snap/snapcraft.yaml:211-226).exec image-garden discard "$SPREAD_SYSTEM_ADDRESS" stops QEMU by its pid file, frees the port and removes a TPM system's runtime state. discard -a stops them all.
exec image-garden discard "$SPREAD_SYSTEM_ADDRESS" (spread.yaml:59), as in the README's backend (README.md:745) and the demo (spread-demo/spread.yaml:40). With exec, the shell is replaced by image-garden, so its output and exit status are the hook's.localhost:PORT, kills the pid in port.PORT.pid and removes port.PORT.pid, port.PORT.system and the TPM run directory (image-garden:1254-1272); any other address exits 1.discard_tpm_run_dir waits for swtpm, stops it and removes its run directory (image-garden:836-859).discard -a does the same for every pid file (image-garden:1221-1250).Each system lists username and password: the distribution's name for both, or root/root; Ubuntu Core takes ubuntu/ubuntu only. SYSTEM.run --query prints them.
root/root and a user named after the group, with that name as password (mk/010-qemu.mk:200-211).ubuntu/ubuntu for every Ubuntu Core system (spread-demo/spread.yaml:135-172).SYSTEM.run --query prints system.users.N.username and .password (mk/010-qemu.mk:63-92); a named instance's script prints its base system's users (mk/020-instances.mk:89).With a non-root username, spread runs scripts with sudo: root, but in the user's login session. For tests that look at sessions, list root/root; Ubuntu Core has no root login.
sudo: ["ALL=(ALL) NOPASSWD:ALL"], and creates root with password root (mk/010-qemu.mk:200-211). Either can be listed in spread.yaml.sudo when the system's username is not root is spread's behaviour, not image-garden's; it is stated here as the maintainer's experience, not read in spread's source for this map./proc/self/loginuid), or variables such as XDG_RUNTIME_DIR and DBUS_SESSION_BUS_ADDRESS that the SSH login set up for the user (sudo resets most of the environment, so which survive depends on its configuration). /run/user/1000 on the slide assumes the user has UID 1000.ubuntu through sudo.Next: system names, allocate and discard on the host, the users, spread in the snap and spread-gitlab-ci.
The backend below is image-garden's own garden backend from spread.yaml (lines 24-72) and the README's "Spread Integration Note" and "Spread Test Framework" sections, at the commit this map describes ("code"). The comments are this map's. The systems list is shortened; nothing here was run.
backends:
garden:
# spread has no image-garden backend of its own: write the hooks.
type: adhoc
allocate: |
# From the image-garden snap, spread puts /snap/bin first on
# PATH; the snap's spread app saved the original PATH.
if [ -n "${SPREAD_HOST_PATH-}" ]; then
PATH="${SPREAD_HOST_PATH}"
fi
# Size the machine. These are read by the .run script.
export QEMU_MEM_OPTION="-m ${SPREAD_QEMU_MEM:-4096}"
if [ -n "${SPREAD_QEMU_SMP:-}" ]; then
export QEMU_SMP_OPTION="-smp $SPREAD_QEMU_SMP"
fi
# spread names carry no architecture: add the host's.
ARCH="${ARCH:-$(uname -m)}"
# spread names cannot hold + or @: turn -plus- and -at- back.
SYSTEM="${SPREAD_SYSTEM//-plus-/+}"
SYSTEM="${SYSTEM/-at-/@}"
# exec: image-garden's output and exit status go to spread.
# --spread: wait for SSH, print <ADDRESS …> or <FATAL …>.
exec image-garden allocate --spread "$SYSTEM"."$ARCH"
discard: |
if [ -n "${SPREAD_HOST_PATH-}" ]; then
PATH="${SPREAD_HOST_PATH}"
fi
# The address allocate printed, localhost:PORT; exec as above.
exec image-garden discard "$SPREAD_SYSTEM_ADDRESS"
systems:
# The user and password image-garden's cloud-init created.
- ubuntu-cloud-24.04:
username: ubuntu
password: ubuntu
- debian-cloud-13:
username: debian
password: debian
- fedora-cloud-43:
username: fedora
password: fedora
# Ubuntu Core allows no root password login.
- ubuntu-core-24-plus-tpm:
username: ubuntu
password: ubuntu
# An instance defined in .image-garden.mk.
- ubuntu-cloud-24.04-at-mc:
username: ubuntu
password: ubuntu| Hook | spread gives it | It must give spread |
|---|---|---|
allocate | SPREAD_SYSTEM, the system's name in spread.yaml | <ADDRESS host:port> on success, <FATAL message> on failure |
discard | SPREAD_SYSTEM_ADDRESS, the address allocate printed | nothing; the machine is gone |
| Situation | Output | Exit status |
|---|---|---|
| SSH banner seen | <ADDRESS localhost:PORT> | 0 |
GARDEN_SSH_WAIT_TIMEOUT (600 s) ran out | <ADDRESS localhost:PORT>, after a warning | 0 |
| QEMU gone before SSH answered | <FATAL SYSTEM exited before SSH became available, see SYSTEM.PORT.serial.log> | 213 |
| the port cannot be probed | <FATAL cannot wait for SSH on port PORT of SYSTEM> | 213 |
| QEMU failed to start | <FATAL last line of SYSTEM.PORT.stderr.log> | 213 |
| the caller of allocate went away | the machine is discarded | 1 |
| Variable | Read by | Meaning |
|---|---|---|
SPREAD_QEMU_MEM | the allocate hook above | memory in MB, 4096 by default |
SPREAD_QEMU_SMP | the allocate hook above | CPU count, QEMU's default if unset |
ARCH | the allocate hook above | the architecture, uname -m by default |
QEMU_MEM_OPTION, QEMU_SMP_OPTION | the .run script | QEMU options for memory and CPUs |
QEMU_SNAPSHOT_OPTION | image-garden allocate | -snapshot by default; empty keeps changes |
GARDEN_SSH_WAIT_TIMEOUT | image-garden allocate | seconds to wait for SSH, 600 by default |
SPREAD_HOST_PATH | both hooks | the PATH spread was started with, set by the snap's spread app |
| username | How scripts run | When to use it |
|---|---|---|
root / root | as root, in root's own login session | tests of sessions, logind, polkit, user services, or anything that reads the login user ID |
the distribution user, such as ubuntu / ubuntu | through passwordless sudo: root, but in the user's login session | most tests; the only choice on Ubuntu Core, which has no root password login |
image-garden: ubuntu-core-24+tpm.x86_64, ubuntu-cloud-24.04@mc.aarch64. spread: no architecture, no +, no @.
BASE@NAME.ARCH, for example ubuntu-cloud-24.04@webserver.x86_64 (mk/020-instances.mk:1-19), from a system defined in data/*.ini: Ubuntu Core systems have modifiers but no instances (README.md:976-979).+ as -plus- and @ as -at- in spread configuration "for compatibility" (README.md:720-732).SYSTEM="${SPREAD_SYSTEM//-plus-/+}" replaces every -plus-; SYSTEM="${SYSTEM/-at-/@}" replaces only the first -at-, since an instance name may contain one.
SYSTEM="${SPREAD_SYSTEM//-plus-/+}" then SYSTEM="${SYSTEM/-at-/@}" (spread.yaml:45-46, README.md:727-728).ubuntu-cloud-24.04-at-mc and ubuntu-core-24-plus-dangerous-plus-tpm (spread-demo/spread.yaml:116, spread-demo/spread.yaml:156).//-plus-/ replaces every occurrence, /-at-/ only the first. The README explains why: "Every -plus- is replaced, but only the first -at-: a name has one @, system names have no -at-, and the instance name after it may" (README.md:731-732).look-at-me on the slide is an example instance name, not one from image-garden.ARCH="${ARCH:-$(uname -m)}", then "$SYSTEM"."$ARCH": one spread.yaml serves x86_64 and aarch64 runners, each at full speed.
ARCH="${ARCH:-$(uname -m)}", then "$SYSTEM"."$ARCH" (spread.yaml:43-47)./dev/kvm, "QEMU emulates the CPU (TCG), many times slower" (README.md:780-781).uname -m prints x86_64, on a 64-bit Arm host aarch64.+tpm selects the TPM rules. @mc selects UBUNTU_24.04@mc_CLOUD_INIT_USER_DATA_TEMPLATE, which installs mc while the image is made.
+tpm systems: UBUNTU_CORE_TPM_RELEASES = 24+tpm 24+dangerous+tpm 26+tpm 26+dangerous+tpm, x86_64 only; +tpm+dangerous is refused with a message to use alphabetical order (mk/050-ubuntu-core.mk:15-21).mc instance and its template (spread-demo/.image-garden.mk:16-23), and the task that needs it (spread-demo/tests/smoke/mc-package/task.yaml:3-7).GROUP_REL@INST, GROUP@INST, GROUP_REL, GROUP, then the default (mk/010-qemu.mk:293-298).No architecture in spread.yaml, credentials for every system, instances for roles, short lowercase instance names, one make target per system.
spread -list, turns -plus- into + for target names, and back into -plus- for spread (spread-demo/Makefile:4-8).SYSTEM@NAME.ARCH.qcow2) and template names (GROUP_REL@NAME_CLOUD_INIT_USER_DATA_TEMPLATE) (mk/020-instances.mk:1-19); lowercase is a convention of this map, not a rule in the code.Next: system names, profiles, instances, Secure Boot and TPM, and how templates are picked.
Read in image-garden at the commit this map describes ("code"): the allocate hook in spread.yaml (lines 43-47), mk/020-instances.mk, the template picker in mk/010-qemu.mk (lines 285-298) and the Ubuntu Core rules in mk/050-ubuntu-core.mk. The rows are worked out from them ("derived") on an x86_64 host; nothing was run. webserver and db are example instances that a project would define in its .image-garden.mk.
| In spread.yaml | Allocated as (x86_64 host) | Templates tried, first defined wins |
|---|---|---|
ubuntu-cloud-24.04 | ubuntu-cloud-24.04.x86_64 | UBUNTU_24.04_…, UBUNTU_…, CLOUD_INIT_USER_DATA_TEMPLATE |
ubuntu-cloud-24.04-at-mc | ubuntu-cloud-24.04@mc.x86_64 | UBUNTU_24.04@mc_…, UBUNTU@mc_…, UBUNTU_24.04_…, UBUNTU_…, CLOUD_INIT_USER_DATA_TEMPLATE |
debian-cloud-13-at-webserver | debian-cloud-13@webserver.x86_64 | DEBIAN_13@webserver_…, DEBIAN@webserver_…, DEBIAN_13_…, DEBIAN_…, CLOUD_INIT_USER_DATA_TEMPLATE |
fedora-cloud-43-at-db | fedora-cloud-43@db.x86_64 | FEDORA_43@db_…, FEDORA@db_…, FEDORA_43_…, FEDORA_…, CLOUD_INIT_USER_DATA_TEMPLATE |
ubuntu-core-24-plus-tpm | ubuntu-core-24+tpm.x86_64 | the Ubuntu Core template; the +tpm rules add Secure Boot and swtpm |
ubuntu-core-24-plus-dangerous-plus-tpm | ubuntu-core-24+dangerous+tpm.x86_64 | as above, from the +dangerous image |
Every … stands for _CLOUD_INIT_USER_DATA_TEMPLATE. An instance exists only when the project's .image-garden.mk defines it with $(eval $(call define-instance,BASE,NAME)). With no template for it, an instance gets its base system's template.
| Line | Replaces | Why |
|---|---|---|
SYSTEM="${SPREAD_SYSTEM//-plus-/+}" | every -plus- | a name can carry several modifiers, as in +dangerous+tpm |
SYSTEM="${SYSTEM/-at-/@}" | the first -at- | a name has one @ and no system name contains -at-, but an instance name may |
.$(uname -m), or $ARCH.username and password for every system; ubuntu on Ubuntu Core.+dangerous+tpm, never +tpm+dangerous.spread-demo/Makefile.spread asks a backend for a machine per system: an SSH address, a user and a password. image-garden gives all three.
username and password and gets the address from image-garden allocate --spread (README.md:736-756).garden backend this way (spread.yaml:24-72).The image is prepared once. Each allocation boots it with -snapshot in the background, on its own port, and nothing it writes is kept.
--premade is given, allocate makes SYSTEM.run and SYSTEM.qcow2 first, under a per-system flock, then checks memory against the launcher (image-garden:1057-1068).127.0.0.1:PORT to the guest's port 22 and starts the launcher with ${QEMU_SNAPSHOT_OPTION=-snapshot}, -daemonize and a pid file (image-garden:1095-1163).QEMU_SNAPSHOT_OPTION="" keeps a machine's changes instead.spread garden:ubuntu-cloud-24.04:tests/smoke/uname allocates one machine, runs the task on it and collects uname.txt.
tests/smoke/uname: summary, artifacts: [uname.txt], execute: uname -a | tee uname.txt (spread-demo/tests/smoke/uname/task.yaml:3-7).spread garden:<system>: for one system at a time (spread-demo/Makefile:4-8).discard stops the machine and frees its port. allocate cleans up after itself when QEMU or its caller goes away; image-garden ps lists what is left.
discard localhost:PORT reads port.PORT.pid under $XDG_RUNTIME_DIR/image-garden/, kills that process and removes the .pid and .system files and a TPM run directory (image-garden:1254-1272).<FATAL … exited before SSH became available, see … serial.log> when QEMU is gone, and discards the machine itself when its caller went away (image-garden:1181-1196).image-garden ps [--all|--stale] lists allocated machines (image-garden:1276-1358).Next: the adhoc backend, system names, spread in the snap, spread-gitlab-ci and cloud-init profiles.
The snap, the container and distribution packages or a source build all carry the same image-garden.mk. They differ in QEMU, cache location, the extras that come along, and how current they are.
image-garden script on the same image-garden.mk, built from data/*.ini and mk/*.mk by the top-level Makefile (Makefile:48-64); the script runs make -f on that file (image-garden:982-993).snap install image-garden adds QEMU for the host architecture and pkgproxy as components, and the configure hook adds spread; other QEMUs, spread-plus and swtpm come on demand. Downloads live in ~/snap/image-garden/common/cache.
snapctl install +qemu-<host arch> +pkgproxy, unless the snap was sideloaded (a revision such as x1) (snap/hooks/install:6-14).+spread while the spread-variant setting is empty (snap/hooks/configure:83-92); the README says so (README.md:163-169).spread, spread-plus, qemu-x86-64, qemu-aarch64, qemu-riscv64, qemu-s390x, qemu-ppc64, qemu-loongarch64, pkgproxy and swtpm (snap/snapcraft.yaml:45-119). The README shows how to add one: snap install image-garden+qemu-aarch64 (README.md:309-334).qemu-patches/guestfwd-unix-socket.patch (snap/snapcraft.yaml:341), the patch the container applies too (Dockerfile:29-32).GARDEN_CACHE_DIR is $SNAP_USER_COMMON/cache, which is ~/snap/image-garden/common/cache (mk/000-garden.mk:9-12). The common directory is not tied to a revision (derived from snapd's layout).One image with QEMU for six architectures, swtpm and OVMF. Run it with --device /dev/kvm and a volume at /var/cache/image-garden; name a pkgproxy with PKGPROXY_URL.
x86_64, aarch64, riscv64, s390x, ppc64 and loongarch64 (Dockerfile:5-54).ovmf, swtpm, curl, make, xorriso, xz-utils and git, sets GARDEN_CACHE_DIR=/var/cache/image-garden and declares that directory a volume (Dockerfile:73-104). It has no spread, no pkgproxy and no entrypoint.docker run --device /dev/kvm --volume $HOME/.cache/image-garden:/var/cache/image-garden image-garden:latest, and the same with podman (README.md:342-382).latest (.gitlab-ci.yml:1231-1278).Packages for Arch Linux (AUR), Debian, openSUSE and Fedora use the host's QEMU, firmware and swtpm. pkgproxy comes from PKGPROXY_URL; downloads go to $XDG_CACHE_HOME/image-garden.
PKGPROXY_URL", and the cache is $XDG_CACHE_HOME (README.md:96-112).GARDEN_CACHE_DIR is $XDG_CACHE_HOME/image-garden, and XDG_CACHE_HOME defaults to ~/.cache (mk/000-garden.mk:9-12).PKGPROXY_URL set, the host is resolved to an IPv4 address when make runs and guests reach it through QEMU's user network; no guestfwd is added (mk/010-qemu.mk:20-44). The snap's socket modes need the patched QEMU; a package never uses them.qemu-system-<arch> from PATH (mk/010-qemu-x86_64.mk:4); a distribution QEMU does not carry the guestfwd patch.make && sudo make install builds image-garden.mk and installs it with the command under /usr/local. The host needs curl, xorriso, qemu-img and the qemu-system-* emulators.
prefix ?= /usr/local; make install puts image-garden in $(bindir) with @PREFIX@, @INCLUDEDIR@, @DOCDIR@ and @VERSION@ filled in, image-garden.mk in $(includedir), the README and NEWS files in $(datarootdir)/doc/image-garden and the man page in $(man1dir); includedir and datarootdir default from prefix but can be set on their own (Makefile:3-46).image-garden.mk is data/000-systems.mk, the sorted mk/*.mk and the sorted data/050-*.gen.mk joined, each .gen.mk written by rulegen.py from one .ini (Makefile:48-64).curl, qemu-system-x86_64, qemu-system-aarch64, qemu-system-riscv64, qemu-system-s390x, qemu-system-ppc64, qemu-system-loongarch64, qemu-img and xorriso, "or the emulators of the architectures you use", and swtpm with the ovmf Secure Boot firmware for the TPM systems (README.md:114-126).xorriso and curl are $(error ...) when missing (mk/000-garden.mk:20-21), as is qemu-img (mk/010-qemu.mk:3); a missing qemu-system-x86_64 is a $(warning ...) (mk/010-qemu-x86_64.mk:4), and the recipe that runs it fails later (derived).make check runs the project's own checks (shellcheck, mypy, the rulegen and download tests).XORRISO, CURL and QEMU_IMG are set with ?= (mk/000-garden.mk:20-21, mk/010-qemu.mk:3), so each is looked for only when the first step that uses it runs; image-garden make list-systems works without any of them (run at v0.8.0 for the nat-deps deck). See what the host needs.The snap and the container are built from the tree on every release tag; the snap's edge channel is built nightly. Distribution packages may be older than upstream. image-garden version and image-garden news tell you what you have.
git describe: a commit that is exactly a tag gets that version and grade stable, any other commit TAG+gitN.HASH and grade devel (snap/snapcraft.yaml:271-299).snap-edge and snap-stable jobs; a nightly schedule exists only to build edge (.gitlab-ci.yml:26-33, .gitlab-ci.yml:128-129).latest (.gitlab-ci.yml:1257-1278).image-garden version prints image-garden VERSION; image-garden news [N] prints the last N "Changes in" sections of NEWS, NEWS.snappy and NEWS.docker, those present in the install (image-garden:909-942). The snap leaves out NEWS.docker, the container NEWS.snappy.Next: the snap, the container, and native packages and source builds, each in its own district.
The comparison table of the README of image-garden, at the commit this map describes (README.md:96-106), checked against the snap's snapcraft.yaml, the Dockerfile and the Makefile ("code"). The age of distribution packages is the maintainer's statement.
| Snap | Container | Native package or source | |
|---|---|---|---|
| Where | Snap Store | container registries | Arch (AUR), Debian, Fedora, openSUSE; or make && make install |
| How current | follows upstream releases | follows upstream releases | distribution packages, such as Debian and Fedora ones, may be older than upstream |
| QEMU | built by the snap, one component per architecture | built into the image | your distribution's |
| guestfwd unix socket patch | yes | yes | no |
| Architectures | x86_64, aarch64, riscv64, s390x, ppc64, loongarch64 | the same six | what your QEMU has |
| UEFI firmware | in the QEMU components | built with QEMU, plus the ovmf package | system packages |
| swtpm, for +tpm systems | optional swtpm component | included | system package |
| spread | the spread component, added at install; spread-plus on demand | no | system package |
| pkgproxy | bundled, or snap set image-garden pkgproxy=… | PKGPROXY_URL | PKGPROXY_URL |
| virtiofsd | bundled, run as image-garden.virtiofsd | no | system package |
QEMU's -snapshot scratch | ~/snap/image-garden/common/tmp, on disk (qemu-var-tmp:9-20) | /var/tmp inside the container | /var/tmp, unless TMPDIR says otherwise |
| Cache | ~/snap/image-garden/common/cache | a volume at /var/cache/image-garden | ~/.cache/image-garden |
| Install | Command |
|---|---|
| Snap | snap install image-garden; more QEMUs with snap install image-garden+qemu-aarch64, swtpm with snap install image-garden+swtpm |
| Container | docker run --device /dev/kvm --volume $HOME/.cache/image-garden:/var/cache/image-garden image-garden:latest image-garden make SYSTEM.run (or podman run) |
| Distribution package | your distribution's package manager |
| Source | make && sudo make install, into /usr/local unless prefix= says otherwise |
Every install then answers image-garden version and image-garden news.
A system name says which operating system, which kind of image, which release and which architecture: ubuntu-cloud-24.04.x86_64. It is the make target and the prefix of every file made for that system.
[ubuntu-cloud-24.04.x86_64] of data/ubuntu.ini, with Arch=x86_64, Boot=efi and Release=24.04 (ubuntu.ini:237-242).NAME.meta-data, NAME.user-data, NAME.qcow2, NAME.run, and the cleanup removes them by the same name (rulegen.py:452-478)..ppc64el); the full list is in the support matrix.GROUP-VARIANT-RELEASE+MODIFIER@INSTANCE.ARCH. The release, the modifiers and the instance are optional; the group, the variant and the architecture are always there.
$GROUP-$VARIANT-$RELEASE.$ARCH is the comment on the field that holds it (rulegen.py:114-117). rulegen.py does not build the name from the parts; it checks only that the section name contains the Arch value, and stops with "Suspicious image … for architecture …" otherwise (rulegen.py:395-405).ubuntu-cloud-24.04.ppc64el with Arch=ppc64: ppc64el contains ppc64 (ubuntu.ini:24-27).[META] keys Group and Variant of each INI file, here Group=ubuntu, Variant=cloud (ubuntu.ini:4-6).[fedora-cloud-42.riscv64] (fedora.ini:80-85); [archlinux-cloud.x86_64] has no Release key (archlinux.ini:8-12). Gentoo is the other system without a release.+dangerous and +tpm. Make stops on +tpm+dangerous with "system modifiers go in alphabetical order: use … +dangerous+tpm …", and on +tpm for an architecture other than x86_64 (050-ubuntu-core.mk:15-21).define-instance makes BASE@NAME.ARCH from a base system and an instance name, for example ubuntu-cloud-24.04@webserver.x86_64 (020-instances.mk:1-19).+dangerous and +tpm systems "variants" of Ubuntu Core (README.md:701-707). In the name they are modifiers; the variant is the word after the group (core).+, @ and the architecture.The group picks the cache directory, the user and the template prefix; the release a per-release template; a modifier extra rules; an instance its own template and disk; the architecture the QEMU. The variant names the kind of image.
Group key for the download directory $(GARDEN_DL_DIR)/GROUP (rulegen.py:448-451, rulegen.py:480-483), the second user of the user-data and its upper-case template prefix (rulegen.py:467-467), and the user that --query reports (rulegen.py:593-597, 010-qemu.mk:57-92). The template makes that user with the group's name as its password (010-qemu.mk:205-211).GROUP_RELEASE@INSTANCE, GROUP@INSTANCE, GROUP_RELEASE, GROUP, then the default CLOUD_INIT_USER_DATA_TEMPLATE (010-qemu.mk:293-298). image-garden itself defines no UBUNTU_24.04_… template; you may, in .image-garden.mk. The release also goes into the guest's host name, ubuntu-24-04, the same in user-data, /etc/hosts and the meta-data's local-hostname (010-qemu.mk:94-104, 010-qemu.mk:196).+dangerous downloads from the dangerous-stable channel instead of stable (050-ubuntu-core.mk:235-239); +tpm sets the machine to q35,smm=on, uses Secure Boot firmware and starts swtpm (050-ubuntu-core.mk:55-68). In the host name a modifier's + becomes -, as a host name label allows no +: ubuntu-core-24+tpm names itself ubuntu-core-24-tpm (010-qemu.mk:94-97, 050-ubuntu-core.mk:141).define-instance gives BASE@NAME.ARCH its own disk image, seed ISO and run script, and inherits the base's boot type, architecture, group and release (020-instances.mk:16-19). Its host name adds the instance, ubuntu-24-04-webserver, in user-data and meta-data alike (020-instances.mk:67-68).Arch and Boot (rulegen.py:804-821); each architecture's QEMU command is in its own mk/010-qemu-ARCH.mk.core into theirs.Variant from [META] (rulegen.py:336-348) into Group.variant. Its only use is the Group.full property (rulegen.py:32-48), and nothing calls full. str(group) is the group's name alone, and that is what the rule templates and --systems-meta use (rulegen.py:824-833).Thirteen INI files, each with Variant=cloud, and the hand-written Ubuntu Core rules, whose names say core. The variant is always in the name, even where there is only one kind.
[META] has Group= the file's name and Variant=cloud, for example fedora.ini:4-6, ubuntu.ini:4-6 and opencloudos.ini:9-11.GROUP-cloud: 139 systems in all (counted from the section headers at the tag).ubuntu-core-R.x86_64 for releases 16 to 26 with their +dangerous forms, ubuntu-core-R.aarch64 from 22 on, and the four +tpm systems on x86_64. Its releases are written 24, 26, not 24.04.almalinux-cloud-{8,9,10}, ubuntu-cloud-{14,16,18,20,22,24,26}.04, ubuntu-core-{16,18,…} and so on (image-garden.1:211-214 and the list after it).Thirteen families, each with the variant cloud, and Ubuntu Core, whose names say core. The variant is always in the name, even where there is only one kind.
cloud: 139 systems in all.ubuntu-core-R.x86_64 for releases 16 to 26 with their +dangerous forms, ubuntu-core-R.aarch64 from 22 on, and the four +tpm systems on x86_64. Its releases are written 24, 26, not 24.04.almalinux-cloud-{8,9,10}, ubuntu-cloud-{14,16,18,20,22,24,26}.04, ubuntu-core-{16,18,…} and so on (image-garden.1:211-214 and the list after it).[META] has Group= the file's name and Variant=cloud, for example fedora.ini:4-6, ubuntu.ini:4-6 and opencloudos.ini:9-11.GROUP-cloud: 139 systems in all (counted from the section headers at the tag).ubuntu-core-R.x86_64 for releases 16 to 26 with their +dangerous forms, ubuntu-core-R.aarch64 from 22 on, and the four +tpm systems on x86_64. Its releases are written 24, 26, not 24.04.Planned by the maintainer: ubuntu-core-, ubuntu-desktop-, ubuntu-server- and ubuntu-cloud- followed by a release and an architecture. Only the core and cloud names exist today.
ubuntu-core-RELEASE, ubuntu-desktop-RELEASE, ubuntu-server-RELEASE and ubuntu-cloud-RELEASE, side by side, each with an architecture after the dot. This comes from the maintainer, not from the source at the tag: there are no desktop or server systems, image sources or rules in v0.8.0, and no date has been given.ubuntu-cloud-… systems of data/ubuntu.ini, Group=ubuntu, Variant=cloud (ubuntu.ini:4-6), and the ubuntu-core-… systems of 050-ubuntu-core.mk:4-16.24, 26 at the tag, Ubuntu's cloud releases 24.04, 26.04. The plan names the pattern, not how each variant writes its release, so the slide shows … where the release goes.cloud or core ones.A distribution with several kinds of image could be named NAME-cloud-R, NAME-server-R and NAME-workstation-R, one INI file each. This is what the scheme allows, not a plan for any distribution.
data/050-NAME.gen.mk, by one run of rulegen.py (Makefile:48-58), and rulegen.py takes Group and Variant from that file's [META] section (rulegen.py:336-348). So a second kind of image is a second INI file; the slide leaves Group open because the group decides more than the name (next scene, for contributors).Variant=cloud, for example fedora.ini:4-6.A distribution with several kinds of image could be named NAME-cloud-R, NAME-server-R and NAME-workstation-R, each built the way cloud images are today. This is what the scheme allows, not a plan for any distribution.
data/050-NAME.gen.mk, by one run of rulegen.py (Makefile:48-58), and rulegen.py takes Group and Variant from that file's [META] section (rulegen.py:336-348). So a second kind of image is a second INI file; the slide leaves Group open because the group decides more than the name (next scene, for contributors).Variant=cloud, for example fedora.ini:4-6.Directories, users and templates key on the group, not the variant. Two variants with one Group share them; Ubuntu Core uses ubuntu-core as its group and ubuntu as its user.
Variant is read from [META] into Group.variant (rulegen.py:336-348); only the Group.full property uses it, and nothing calls full (rulegen.py:32-48). str(group) and name_upper are the group's name alone.$(GARDEN_DL_DIR)/GROUP: (rulegen.py:448-451), the meta-data, the user and the template prefix (rulegen.py:460-467) and the download paths (rulegen.py:474-483).GROUP_RELEASE@INSTANCE, GROUP@INSTANCE, GROUP_RELEASE, GROUP and the default (010-qemu.mk:293-298). The host name is group and release too, ubuntu-24-04, in user-data and meta-data (010-qemu.mk:94-104, 010-qemu.mk:196).Group=ubuntu and another Variant would put its downloads in dl/ubuntu/ next to the cloud images, use the same UBUNTU_R… templates and hostnames for equal releases, emit a second recipe for the dl/ubuntu directory rule, and two images with the same local file name in the two files would not be reported.ubuntu-core as the download directory and the group, only:ubuntu and ubuntu as the users (050-ubuntu-core.mk:25-25, 050-ubuntu-core.mk:111-127); its host names start with ubuntu-core too, as in ubuntu-core-24-tpm, and pick templates with the key UBUNTU_CORE, whose base template is UBUNTU_CORE_CLOUD_INIT_USER_DATA_TEMPLATE (050-ubuntu-core.mk:179-179).Variant and, if it must not share with an existing family, its own Group; or hand-written rules in mk/050-*.mk, as Ubuntu Core does. Which of these the planned Ubuntu variants will use is not decided in the source.Next: spread names, the support matrix, the template order, named instances, Ubuntu Core and its modifiers, and, for contributors, adding a system.
GROUP-VARIANT[-RELEASE][+MODIFIER…][@INSTANCE].ARCH, as in ubuntu-cloud-24.04.x86_64.Read in rulegen.py, data/*.ini, mk/010-qemu.mk, mk/020-instances.mk, mk/050-ubuntu-core.mk, the Makefile, the README and the manual page of image-garden at the commit in garden.commit ("code"). The count of systems was made from the section headers of data/*.ini at the tag. What two variants of one group would share is reasoned from the code and not tried ("derived"). The planned Ubuntu names come from the maintainer and are not in v0.8.0 ("planned").
GROUP-VARIANT[-RELEASE][+MODIFIER…][@INSTANCE].ARCH
| Part | Example | Where it comes from |
|---|---|---|
| GROUP | ubuntu, fedora, opensuse | Group in the INI file's [META] section (ubuntu.ini:4-6); ubuntu-core in the hand-written Ubuntu Core rules |
| VARIANT | cloud, or core for Ubuntu Core | Variant in [META], cloud in all thirteen files; core is written into the Ubuntu Core rules |
| RELEASE | 24.04, 42, tumbleweed, 24 for Ubuntu Core; none for Arch Linux and Gentoo | Release in the system's section |
| +MODIFIER | +dangerous, +tpm, in alphabetical order | Ubuntu Core rules (050-ubuntu-core.mk:15-21) |
| @INSTANCE | @webserver | define-instance in .image-garden.mk (020-instances.mk:1-19) |
| ARCH | x86_64, aarch64, riscv64, s390x, ppc64 (named ppc64el), loongarch64 | Arch (rulegen.py:23-29) |
In the INI files the whole name is the section name, written by hand; rulegen.py checks only that it contains the Arch value (rulegen.py:395-405).
| Part | Selects | Source |
|---|---|---|
| GROUP | the download directory dl/GROUP/, the second user and its password, the upper-case template prefix, the hostname's first part | rulegen.py:447-483, 010-qemu.mk:94-104, 010-qemu.mk:196-211 |
| VARIANT | nothing in the rules; it names the kind of image | rulegen.py:32-48, rulegen.py:336-348 |
| RELEASE | a GROUP_RELEASE_CLOUD_INIT_USER_DATA_TEMPLATE if one is defined; the hostname's second part | 010-qemu.mk:293-298 |
| +dangerous | the dangerous-stable image channel | 050-ubuntu-core.mk:235-239 |
| +tpm | q35,smm=on, Secure Boot firmware, swtpm and a NAME.tpm/ state directory | 050-ubuntu-core.mk:55-68 |
| @INSTANCE | GROUP_RELEASE@INSTANCE and GROUP@INSTANCE templates; its own disk, seed and run script | 020-instances.mk:16-19, 010-qemu.mk:293-298 |
| ARCH | the run and provisioning rules, and with them the QEMU and its machine | rulegen.py:804-821 |
| Name | What it is |
|---|---|
ubuntu-cloud-24.04.x86_64 | Ubuntu 24.04 LTS cloud image on x86_64 |
fedora-cloud-42.riscv64 | Fedora 42 on RISC-V |
archlinux-cloud.x86_64 | Arch Linux, rolling, no release |
ubuntu-core-24+dangerous+tpm.x86_64 | Ubuntu Core 24, dangerous model, Secure Boot and a TPM |
ubuntu-cloud-24.04@webserver.x86_64 | a named instance of Ubuntu 24.04 |
The group, the release and the instance joined with dashes, with every . and + turned into -, as a host name label allows neither (010-qemu.mk:94-97). user-data, /etc/hosts and the meta-data's local-hostname and instance-id all use it.
| System | Host name |
|---|---|
ubuntu-cloud-24.04.x86_64 | ubuntu-24-04 |
ubuntu-cloud-24.04@webserver.x86_64 | ubuntu-24-04-webserver |
ubuntu-core-24+tpm.x86_64 | ubuntu-core-24-tpm |
archlinux-cloud.x86_64 | archlinux |
NAME.run, NAME.qcow2, NAME.qcow2.log, NAME.user-data, NAME.meta-data, NAME.seed.iso, and on UEFI systems NAME.efi-code.qcow2 and NAME.efi-vars.qcow2; +tpm systems also NAME.tpm/.
The maintainer plans to name Ubuntu systems by kind of image, side by side:
| Planned name | Kind | At v0.8.0 |
|---|---|---|
ubuntu-core-RELEASE | Ubuntu Core | exists, as ubuntu-core-24 and the others |
ubuntu-desktop-RELEASE | desktop | not in the source |
ubuntu-server-RELEASE | server | not in the source |
ubuntu-cloud-RELEASE | cloud image | exists, as ubuntu-cloud-24.04 and the others |
Each is followed by .ARCH. This is a plan, not a feature of v0.8.0: there are no desktop or server images, sources or rules at the tag, and no date. The same pattern could name other distributions' editions; nothing of the kind is planned in the source.
Derived from the code, not tried. Directories, the second user, hostnames and templates key on the group, never on the variant. Two INI files with the same Group and different Variant would share dl/GROUP/ and the GROUP_RELEASE templates, and rulegen.py's file-name clash check, which runs on one INI file at a time (rulegen.py:753-775, Makefile:57-58), would not compare them. Ubuntu Core avoids this with hand-written rules that use ubuntu-core as the group and ubuntu as the user (050-ubuntu-core.mk:111-127).
spread names have no architecture and no + or @: ubuntu-core-24-plus-tpm, ubuntu-cloud-24.04-at-webserver. See spread names.
image-garden builds test VMs from distributions' own cloud images with curl and QEMU. image-garden make ubuntu-cloud-24.04.x86_64.run gives you a script that boots Ubuntu 24.04.
curl and qemu), simple insecure access, and generated .run scripts that show the exact QEMU command (README.md:11-23).ubuntu-cloud-24.04.x86_64.run and runs it (README.md:69-89).x86_64, aarch64, riscv64, s390x, ppc64 and loongarch64 (rulegen.py:23-29). Which distribution runs on which is in the support matrix.image-garden carries a list of the systems it knows. Its build turns that list into make rules and joins them with hand-written ones into image-garden.mk, installed beside the image-garden command.
[ubuntu-cloud-24.04.x86_64] in data/ubuntu.ini: URL, SHA256SUMS, Arch=x86_64, Boot=efi, Release=24.04 (ubuntu.ini:237-242). The slide shows the five keys in plain words.image-garden.mk (Makefile:48-64). The snap, the container and the distribution packages carry the file that build produced.make install puts image-garden.mk in the include directory and the image-garden script in the bin directory (Makefile:30-46); the script runs make -f on that file (image-garden:982-993)..image-garden.mk.rulegen.py turns each section of data/*.ini into make rules. The build concatenates data/000-systems.mk, mk/*.mk and data/050-*.gen.mk into image-garden.mk.
[ubuntu-cloud-24.04.x86_64]: URL, SHA256SUMS, Arch=x86_64, Boot=efi, Release=24.04 (ubuntu.ini:237-242). The file's [META] section sets Group=ubuntu and Variant=cloud (ubuntu.ini:4-6).rulegen.py takes INI files as arguments and prints make rules on standard output; with --systems-meta FILE it appends each system's group, release, architecture and boot type to FILE (rulegen.py:741-752)../rulegen.py data/X.ini > data/050-X.gen.mk per file, builds data/000-systems.mk from all of them, and concatenates data/000-systems.mk, the sorted mk/*.mk and the sorted data/050-*.gen.mk into image-garden.mk (Makefile:48-64).make install puts image-garden.mk in the include directory and the image-garden script in the bin directory (Makefile:30-46); the script runs make -f on that file (image-garden:982-993).*.gen.mk files and image-garden.mk are build output and not in git.The checksum list and the image come over HTTPS, through pkgproxy if there is one, and nothing is used until they match. The download is cached and linked as ubuntu-cloud-24.04.x86_64.qcow2.
SHA256SUMS, the download rule runs image-garden download-with-sha256sums URL SUMS DIR FILE, then links DIR/<system>.qcow2 to the downloaded file (rulegen.py:510-514). SHA512SUMS takes precedence over SHA256SUM, which takes precedence over SHA256SUMS (rulegen.py:498-514).https://cloud-images.ubuntu.com/… (ubuntu.ini:238-239); every image definition uses https.--continue-at - (image-garden:310-326).flock on FILE.lock, so systems that share one image, such as ubuntu-core-24 and ubuntu-core-24+tpm, do not fetch it twice (image-garden:470-477).sha256sum --check; on failure both the image and its checksum file are removed and the whole download runs once more (image-garden:480-559).$XDG_CACHE_HOME/image-garden/dl (by default ~/.cache/image-garden/dl); the snap and the container put it elsewhere (image-garden:20-29, 000-garden.mk:9-12).A 64G copy-on-write overlay on the download, a cidata seed ISO, and one provisioning boot. cloud-init disables itself and powers off; the console log is ubuntu-cloud-24.04.x86_64.qcow2.log.
X.qcow2 is created with qemu-img create -f qcow2 -b <download> -F qcow2 X.qcow2 64G, then booted with the seed attached as a read-only virtio-blk CD-ROM, its output piped through tee X.qcow2.log (rulegen.py:593-610). The size is QEMU_IMG_SIZE = 64G (010-qemu.mk:8).xorriso -as genisoimage -volid cidata from the user-data and meta-data files (010-qemu.mk:268-279).power_state powers off at once (line 190); ssh_pwauth: true (197); users root/root and a user named after the distribution with the same password and passwordless sudo (from 200); PermitRootLogin yes appended to sshd_config; datasource_list: [NoCloud]; the last command, touch /etc/cloud/cloud-init.disabled (246)..run boots in the foreground and keeps changes. image-garden allocate boots it in the background with -snapshot and prints <ADDRESS localhost:PORT> for spread; discard stops it.
.run script is written line by line by a make macro; it fills defaults for QEMU_MEM_OPTION, QEMU_SMP_OPTION, QEMU_DISPLAY_OPTION and the other QEMU_*_OPTION variables, adds "$@" and runs QEMU (010-qemu-x86_64.mk:49-108). With --query it prints the memory size and the users (010-qemu.mk:63-92). The two values on the slide are examples, not defaults: the default memory is 2048 MiB (010-qemu.mk:9).image-garden allocate builds the system if needed, picks a free port between 5000 and 9999 (image-garden:1100), forwards 127.0.0.1:PORT to the guest's port 22 (image-garden:1107), and runs the .run script with -snapshot (unless QEMU_SNAPSHOT_OPTION says otherwise), -daemonize and a pid file (image-garden:1153-1163).--spread it waits for the SSH banner and prints <ADDRESS localhost:PORT>, else just localhost:PORT (image-garden:1203-1205).garden backend is type: adhoc, with allocate running exec image-garden allocate --spread and discard running exec image-garden discard (spread.yaml:24-60).pkgproxy caches what guests download. image-garden ships as native packages, a container and a snap. GitLab CI components and a GitHub action are built on it.
guestfwd to 10.0.2.100:3142 when its socket is local, or through a URL (010-qemu.mk:20-44). The user-data then asks pkgproxy once, adds a pkgproxy hosts entry, runs pkgproxy's apt setup on Debian and Ubuntu and its snap setup on all but Alpine, and sets GOPROXY (010-qemu.mk:127-185).qemu-patches/guestfwd-unix-socket.patch; a native package uses the distribution's QEMU.Next: the support matrix, the build-time data, the first boot, the runtime targets, the three ways to install, pkgproxy and the projects built on it.
data/ubuntu.ini → rulegen.py → image-garden.mk → download and verify → X.qcow2 overlay and one provisioning boot → X.run → allocate.a5785d52). Source links point at f6a1d87e, whose code v0.8.1 shares apart from version strings.Everything here was read in the image-garden source at the commit in garden.commit ("code"); the file names for ubuntu-cloud-24.04.x86_64 follow from the rules ("derived"). Nothing was run for this page.
For image-garden make ubuntu-cloud-24.04.x86_64.run, with DL the download cache (~/.cache/image-garden/dl for a source install):
| Step | File | Made by |
|---|---|---|
| 1 | DL/ubuntu/ubuntu-cloud-24.04.x86_64.url | the URL key, written out |
| 2 | DL/ubuntu/ubuntu-cloud-24.04.x86_64.filename | the local file name, here the URL's basename |
| 3 | DL/ubuntu/noble-server-cloudimg-amd64.img | image-garden download-with-sha256sums |
| 4 | DL/ubuntu/ubuntu-cloud-24.04.x86_64.qcow2 | a symlink to step 3 |
| 5 | ubuntu-cloud-24.04.x86_64.user-data, .meta-data | the cloud-init templates |
| 6 | ubuntu-cloud-24.04.x86_64.seed.iso | xorriso, volume cidata |
| 7 | efi-code.x86_64.img, efi-vars.x86_64.img | copied from the host's or the snap's EDK2 |
| 8 | ubuntu-cloud-24.04.x86_64.efi-code.qcow2, .efi-vars.qcow2 | qemu-img convert, one variable store per system |
| 9 | ubuntu-cloud-24.04.x86_64.qcow2 (and .qcow2.log) | a 64G overlay on step 4, then the provisioning boot |
| 10 | ubuntu-cloud-24.04.x86_64.run | the launcher script |
Files 5 to 10 are made, in the order make -n prints them, in the current directory, or in .image-garden/ when that directory exists. More in the target chain.
| Command | What it does |
|---|---|
image-garden make GOAL | runs make on image-garden.mk for GOAL, such as SYSTEM.run or SYSTEM.qcow2 |
image-garden make list-systems | lists every system |
./SYSTEM.run | boots the system in the foreground; changes are kept |
./SYSTEM.run --query | prints the memory size and the users and passwords |
image-garden allocate [--spread] SYSTEM | boots it in the background with -snapshot and SSH on a local port |
image-garden discard ADDRESS or -a | stops one allocated VM, or all |
image-garden ps | lists allocated VMs |
image-garden rebase SYSTEM.ARCH | points a prepared overlay at its download in this machine's cache, even when the old cache is gone; SYSTEM.ARCH.qcow2 works too |
image-garden make clean, distclean | removes what make built in the project and the cache links; distclean also removes the downloads |
The README's security notice: fixed passwords and SSH password logins, traded for easy access in tests. The images are for testing, development and CI, not for production.
root/root, and the distribution's name for the user account), SSH password authentication on by default, guest apt sources switched from HTTPS to HTTP so that pkgproxy can cache packages, and images and checksum lists downloaded over HTTPS, each image checked against its checksum, and ends: "These images are NOT suitable for production use", intended for full-system testing, development and CI/CD (README.md:25-38).Every cloud system has root/root and a user named after the distribution, such as ubuntu/ubuntu, with passwordless sudo. .run --query prints them.
root with plain_text_passwd: root and a user named by the template's second argument, the group (ubuntu here), with the same word as password, groups: users and sudo: ["ALL=(ALL) NOPASSWD:ALL"], both with lock_passwd: false and /bin/bash (mk/010-qemu.mk:200-211).X.run --query prints vm.memory_mb and system.users.N.username and .password: root then the distribution user, or only ubuntu for Ubuntu Core (mk/010-qemu.mk:57-92). Cloud systems pass root distro (rulegen.py:127), Ubuntu Core only:ubuntu (mk/050-ubuntu-core.mk:25).system.users.0 from --query to log in (snapcraft-gitlab-ci bin/snapcraft-vm:374-376).ubuntu with --extrausers and allows no root password login (mk/050-ubuntu-core.mk:166-167, README.md:699-709).ubuntu-cloud-24.04.x86_64; vm.memory_mb=2048 is the default QEMU_MEM_SIZE (mk/010-qemu.mk:9).cloud-init enables SSH password authentication; image-garden appends UsePam yes and PermitRootLogin yes to sshd_config and comments out PermitRootLogin prohibit-password.
ssh_pwauth: true is set in the user-data (mk/010-qemu.mk:197) and again in /etc/cloud/cloud.cfg.d/99-image-garden.cfg (mk/010-qemu.mk:221-227)./root/sshd_config.APPEND holds UsePam yes and PermitRootLogin yes (mk/010-qemu.mk:212-220); runcmd appends it to /etc/ssh/sshd_config, removes it, and comments out PermitRootLogin prohibit-password with sed (mk/010-qemu.mk:241-243). sshd takes the first value it reads for a keyword, so commenting out the earlier line is what lets the appended yes apply (derived from sshd_config(5)).-nographic, which puts the serial console in your terminal (mk/010-qemu.mk:13); the quick start logs in there as ubuntu/ubuntu or root/root (README.md:77-83).ubuntu-24-04 (mk/010-qemu.mk:94-97, mk/010-qemu.mk:196).The only data source is the cidata seed ISO; datasource_list: [NoCloud] keeps cloud-init from probing clouds, and /etc/cloud/cloud-init.disabled turns it off after the first boot.
%.seed.iso is made with xorriso -as genisoimage -volid cidata -joliet -rock -graft-points user-data=… meta-data=… (mk/010-qemu.mk:263-279); the provisioning boot attaches it as a read-only virtio-blk CD-ROM (rulegen.py:601-609)./etc/cloud/cloud.cfg.d/99-image-garden.cfg with datasource_list: [NoCloud], "to avoid probing cloud-specific network services" (mk/010-qemu.mk:221-230).touch /etc/cloud/cloud-init.disabled (mk/010-qemu.mk:246); cloud-init does not run on a boot that finds that file (derived from cloud-init's documentation).cidata label (derived: cloud-init's NoCloud data source).Images and checksum lists come over HTTPS or through pkgproxy, and an image is used only when its checksum matches. In the guest, apt's sources are switched from https to http for caching; apt's signatures still apply.
data/*.ini is https, for example ubuntu.ini:237-242.download-with-sha256sums checks the image with sha256sum; on a mismatch it removes the image and the checksum file and runs the download once more (image-garden:460-559). Systems with SHA512SUMS or a literal SHA256SUM are checked the same way.https:// to http:// in every .list and deb822 .sources file under /etc/apt (mk/010-qemu.mk:244). apt verifies the archive's signed Release files and the package checksums whatever the transport (derived: apt's behaviour).User-mode networking takes no connections from outside. allocate forwards 127.0.0.1:PORT to the guest's SSH, which every local user can reach; the guest reaches the host's loopback at 10.0.2.2. Use your own machine or an ephemeral runner.
.run script uses -netdev user, QEMU's user-mode network, with no forwarded port of its own (mk/010-qemu-x86_64.mk:8-11); the README notes that a machine started with the .run script cannot be reached with ssh (README.md:85-89). That user-mode networking accepts no connection from outside unless a port is forwarded is QEMU's behaviour (derived).hostfwd=tcp:127.0.0.1:PORT-:22 (image-garden:1100-1107). Any process on the host, of any user, can connect to 127.0.0.1 (derived).guestfwd (mk/010-qemu.mk:31-34).Next: allocate and its port, the .run script, and the users, SSH settings and seed in the first boot district.
Read in the image-garden source at the tag in garden.commit ("code"): the common user-data template in mk/010-qemu.mk, the download helpers in image-garden, the network options in mk/010-qemu-*.mk and the README's security notice, which agrees with the code. How QEMU's user network, sshd, cloud-init and apt behave is general knowledge of those programs ("derived"). Nothing was run for this page.
| Setting | Value | Where |
|---|---|---|
| root password | root | user-data users, mk/010-qemu.mk:200-204 |
| second user | the group name, such as ubuntu, password the same | mk/010-qemu.mk:205-211 |
| sudo | ALL=(ALL) NOPASSWD:ALL for the second user | mk/010-qemu.mk:209 |
| SSH password login | ssh_pwauth: true | mk/010-qemu.mk:197, :227 |
| sshd | UsePam yes, PermitRootLogin yes appended; PermitRootLogin prohibit-password commented out | mk/010-qemu.mk:212-243 |
| cloud-init sources | datasource_list: [NoCloud] | mk/010-qemu.mk:221-230 |
| cloud-init afterwards | /etc/cloud/cloud-init.disabled | mk/010-qemu.mk:246 |
| apt sources | https:// rewritten to http:// in the .list and .sources files under /etc/apt | mk/010-qemu.mk:244 |
Ubuntu Core differs: one user, ubuntu/ubuntu, and no root password login (Ubuntu Core). Per-distribution changes are in per-distro quirks.
| From | How | Notes |
|---|---|---|
| your terminal | the serial console of ./SYSTEM.run (-nographic) | the passwords above |
| any process on the host | 127.0.0.1:PORT of an allocated machine | allocate's hostfwd, port 5000 to 9999 |
| other machines | no way in | user-mode networking, no forward to other addresses |
| the guest, outward | the network through the host, the host's loopback at 10.0.2.2, pkgproxy at 10.0.2.100 | derived from QEMU's user network |
Two systems, alpine-cloud-3.x86_64 and alpine-cloud-3.aarch64, both booting with EFI, each pinned to one point release that a new image-garden moves forward.
data/alpine.ini has [META] with Group=alpine, Variant=cloud, and two sections, alpine-cloud-3.x86_64 and alpine-cloud-3.aarch64, both Boot=efi and Release=3 (alpine.ini:4-20).PKGPROXY_RUNCMD_SETUP = $(if $(filter alpine,$1),,snap): every group but alpine gets pkgproxy's snap script (010-qemu.mk:130).…/alpine/v3.24/releases/cloud/alpine-3.24.4-x86_64-cloudinit-r0.qcow2, checked with SHA-512 against the bare hash in ….qcow2.sha512.
URL=https://dl-cdn.alpinelinux.org/alpine/v3.24/releases/cloud/alpine-3.24.4-x86_64-cloudinit-r0.qcow2 and SHA512SUMS= the same URL plus .sha512; for aarch64 alpine-3.24.4-aarch64-cloudinit-r0.qcow2 (alpine.ini:8-20).SHA512SUMS= gives the download-with-sha512sums rule (rulegen.py:498-502). Its reader takes HASH NAME, HASH *NAME, the BSD format, or a file whose only non-empty line is a bare hash of the right length, "as published by Alpine Linux next to each image" (image-garden:75-92, data/README.md:59-61). NEWS: Alpine images were checked against a hash copied into image-garden by hand until this format was accepted (NEWS:166-170).$(GARDEN_DL_DIR)/alpine/; the system's link moves to the new one when the URL changes (see when upstream moves on). The old file stays until you delete it.cloudinit images carry cloud-init, where Alpine's other cloud images use its own tiny-cloud, is Alpine's practice (derived).Users root/root and alpine/alpine, host name alpine-3. With pkgproxy: /etc/hosts and GOPROXY only; no apt, no snap.
root/root and alpine/alpine in group users, with sudo: ["ALL=(ALL) NOPASSWD:ALL"] and shell: /bin/bash (010-qemu.mk:200-211, rulegen.py:467); the host name is alpine-3 (010-qemu.mk:94-104).bootcmd setup script (apt only for debian and ubuntu) and no runcmd one (snap for every group but alpine) (010-qemu.mk:129-130); both batches still add pkgproxy to /etc/hosts (010-qemu.mk:132-134, 010-qemu.mk:156-168), and GOPROXY is appended to /etc/environment (010-qemu.mk:170-180).-q -T 5 -t 1; the comment says "GNU wget would try 20 times; busybox wget takes -t and ignores it", and a guest with neither leaves no mark (010-qemu.mk:141-148)./etc/apt exists (010-qemu.mk:244). No file under mk/ names Alpine.ALPINE_CLOUD_INIT_USER_DATA_TEMPLATE in spread-demo/.image-garden.mk: the common template, two GRUB lines and packages: bash, sudo, tar.
$(CLOUD_INIT_USER_DATA_TEMPLATE), then - sed -i -E -e 's/GRUB_TIMEOUT=[0-9]+/GRUB_TIMEOUT=0/' /etc/default/grub and - grub-mkconfig -o /boot/grub/grub.cfg, then packages: with bash, sudo and tar (spread-demo/.image-garden.mk:4-14). The comment names xz, which the list does not install.runcmd list, which ends the common template (010-qemu.mk:238-246): they run after touch /etc/cloud/cloud-init.disabled, in the same first boot.ALPINE_CLOUD_INIT_USER_DATA_TEMPLATE is the group name the picker tries after the release and instance names (010-qemu.mk:293-298), so it applies to both architectures, and to named instances of alpine-cloud-3 that have no template of their own.shell: /bin/bash and the second user a sudo rule (010-qemu.mk:200-211). Whether Alpine's cloud image ships bash, sudo and GNU tar is not in the source (derived: a minimal Alpine has BusyBox's ash and tar).alpine-cloud-3 with username: alpine, password: alpine (spread-demo/spread.yaml:188-191).musl, not glibc; BusyBox tools; apk; OpenRC, not systemd; no snapd. Small and quick to boot.
alpine (010-qemu.mk:130), a probe written for BusyBox's wget (010-qemu.mk:141-148), and the spread demo installing bash, sudo and GNU tar (spread-demo/.image-garden.mk:4-14).alpine-cloud-3 with spread on both architectures; on a Raspberry Pi 5 the aarch64 job took 2.6 minutes, the shortest of its jobs (.gitlab-ci.yml:889-895).Next: templates, cloud-init hooks, spread, pkgproxy in the user-data, checksums and the support matrix.
Read in data/alpine.ini, rulegen.py, mk/010-qemu.mk, the image-garden script, data/README.md, spread-demo/.image-garden.mk, README.md, NEWS and .gitlab-ci.yml of image-garden at the commit in garden.commit ("code"). What Alpine is built from, musl, BusyBox, apk and OpenRC, is general knowledge ("derived"). Nothing was run for this page.
| System | Release | Point release in the URL | Boot | Image | Host name |
|---|---|---|---|---|---|
alpine-cloud-3.x86_64 | 3 | 3.24.4 | efi | alpine-3.24.4-x86_64-cloudinit-r0.qcow2 | alpine-3 |
alpine-cloud-3.aarch64 | 3 | 3.24.4 | efi | alpine-3.24.4-aarch64-cloudinit-r0.qcow2 | alpine-3 |
image https://dl-cdn.alpinelinux.org/alpine/vMAJOR.MINOR/releases/cloud/alpine-VERSION-ARCH-cloudinit-r0.qcow2 checksum the image URL + .sha512
ARCH is x86_64 or aarch64. The .sha512 file holds one bare SHA-512 hash, which the download helper accepts as the file's only non-empty line of 128 hex digits; it is saved in the cache as FILE.sha512sums. A new point release in a new image-garden is a new file name, so it is downloaded afresh; the old one stays in the cache's alpine/ directory until you remove it.
| What | On Alpine | Source |
|---|---|---|
| Users | root/root; alpine/alpine in group users, sudo rule, shell /bin/bash | 010-qemu.mk:200-211 |
| Host name | alpine-3 | 010-qemu.mk:94-104 |
| SSH | password logins, root may log in | 010-qemu.mk:212-243 |
| apt sources | nothing: there is no /etc/apt | 010-qemu.mk:244 |
| pkgproxy, bootcmd | /etc/hosts entry and reachability probe (curl, or wget as BusyBox has it); no setup script | 010-qemu.mk:127-162 |
| pkgproxy, runcmd | /etc/hosts entry again; no snap setup, for Alpine alone | 010-qemu.mk:164-168 |
| pkgproxy, files | GOPROXY appended to /etc/environment | 010-qemu.mk:170-180 |
| Distribution quirks | none in mk/ | per-distro quirks |
From spread-demo/.image-garden.mk:4-14. Put it in your project's .image-garden.mk to get the same image:
# For compatibility with spread, pre-install sudo and bash, xz and GNU tar. # Edit grub configuration for the system to boot faster. define ALPINE_CLOUD_INIT_USER_DATA_TEMPLATE $(CLOUD_INIT_USER_DATA_TEMPLATE) - sed -i -E -e 's/GRUB_TIMEOUT=[0-9]+/GRUB_TIMEOUT=0/' /etc/default/grub - grub-mkconfig -o /boot/grub/grub.cfg packages: - bash - sudo - tar endef
$ image-garden make alpine-cloud-3.x86_64.run $ ./alpine-cloud-3.x86_64.run --query
In spread.yaml the system is alpine-cloud-3, with username: alpine and password: alpine (spread-demo/spread.yaml:188-191).
Four systems: amazonlinux-cloud-2 and amazonlinux-cloud-2023, each on x86_64 and aarch64, from cdn.amazonlinux.com.
data/amazonlinux.ini has Group=amazonlinux, Variant=cloud and four sections: amazonlinux-cloud-2 and amazonlinux-cloud-2023, each .x86_64 and .aarch64, all with URLProgram instead of URL (amazonlinux.ini:4-42).https://cdn.amazonlinux.com/os-images/latest/kvm/ and …/kvm-arm64/ for 2, https://cdn.amazonlinux.com/al2023/os-images/latest/kvm/ and …/kvm-arm64/ for 2023.neoverse-n1 for aarch64 (README.md:621-625).ubuntu-cloud-24.04.x86_64 names its image with a fixed URL (ubuntu.ini:237-242).The first make fetches Amazon's SHA256SUMS list with curl, and awk prints the KVM image's URL; the same list checks the download. The version in the URL goes into the cached name, such as amazonlinux-cloud-2023-2023.12.20261120.0.x86_64.qcow2.
SHA256SUMS list with curl, and awk prints the first KVM qcow2 for the architecture; the same list checks the download, and the version becomes part of the cached name (amazonlinux.ini:26-33).al2023-kvm-2023.12.20261120.0-kernel-6.1-x86_64.xfs.gpt.qcow2 and amzn2-kvm-2.0.20261120.0-x86_64.xfs.gpt.qcow2 ("run"), and the local name the template gives the first.$GARDEN_DL_DIR/amazonlinux/.URLProgram=$(CURL) https://cdn.amazonlinux.com/al2023/os-images/latest/kvm/SHA256SUMS | awk '$$2 ~ /^al2023-kvm-[^ ]*-x86_64\.xfs\.gpt\.qcow2$$/ { print "https://cdn.amazonlinux.com/al2023/os-images/latest/kvm/"$$2; exit }', with URLPattern, LocalFilenameTemplate=amazonlinux-cloud-2023-@1.x86_64.qcow2 and SHA256SUMS pointing at the same list (amazonlinux.ini:26-33). The other three sections differ only in directory, prefix (amzn2-kvm- for 2) and architecture (arm64 in Amazon's names)..url file (rulegen.py:526-530); the .filename rule applies URLPattern and LocalFilenameTemplate (rulegen.py:546-591); the download is checked with download-with-sha256sums against SHA256SUMS (rulegen.py:496-517), which looks up the local name and falls back to the URL's basename (image-garden:508-515).amazonlinux-cloud-2.x86_64 boots with BIOS, the rest with UEFI. Both aarch64 systems use Fedora's EDK2 and -cpu neoverse-n1.
amazonlinux-cloud-2.x86_64 has Boot=bios; the other three Boot=efi (amazonlinux.ini:8-42). With bios, the .run script has no firmware files and QEMU uses its default BIOS (sys-boot; SeaBIOS is derived).amazonlinux-cloud-2 and amazonlinux-cloud-2023 are in GARDEN_AARCH64_FEDORA_EDK2_SYSTEMS, the aarch64 systems "whose shim or grub predate what newer EDK2 enforces" (mk/010-qemu-aarch64.mk:114-145).mk/050-amazonlinux-2.mk sets QEMU_CPU_AARCH64=neoverse-n1 for the .qcow2 and .run of both aarch64 systems (mk/050-amazonlinux-2.mk:10-11); the default is max (mk/010-qemu-aarch64.mk:5). The commit that added it, 3477e1a, says it "fixes booting for both" and "requires sufficiently new ARM CPU if used natively".AMAZONLINUX_2_CLOUD_INIT_USER_DATA_TEMPLATE adds shutdown --poweroff now; 2023 uses the common template. Users root/root and amazonlinux/amazonlinux.
AMAZONLINUX_2_CLOUD_INIT_USER_DATA_TEMPLATE is $(BASE_CLOUD_INIT_USER_DATA_TEMPLATE) plus - shutdown --poweroff now (mk/050-amazonlinux-2.mk:4-8). The picker tries the group-and-release name first (mk/010-qemu.mk:285-298); for 2023 there is none, so the common template applies.power_state (mk/010-qemu.mk:187-195).root/root and amazonlinux/amazonlinux with passwordless sudo; the group is the user's name (rulegen.py:467, mk/010-qemu.mk:200-211). Host names amazonlinux-2 and amazonlinux-2023. ec2-user is the default user of Amazon's images on EC2, which a users: list without default does not create (derived).snap setup script and GOPROXY, no script for yum or dnf (mk/010-qemu.mk:127-180).BASE_CLOUD_INIT_USER_DATA_TEMPLATE, so a project that redefines CLOUD_INIT_USER_DATA_TEMPLATE in .image-garden.mk changes every system but Amazon Linux 2 (and Gentoo); define AMAZONLINUX_2_CLOUD_INIT_USER_DATA_TEMPLATE too, keeping its shutdown line.Amazon Linux 2 has an announced end of support; 2023 is based on Fedora and uses dnf. The build found first is kept until a makefile changes. On Arm hosts, neoverse-n1 needs a recent CPU.
amzn2-kvm-2.0.20261120.0, on 21 November 2026 ("run")..url file depends only on the makefiles, so the program runs again only when image-garden.mk or .image-garden.mk changes or the file is removed (rulegen.py:526-530); see when upstream moves on.QEMU_ACCEL_MACHINE_PROP is read by the .run script; its default is ,accel=kvm:tcg when QEMU supports KVM (README.md:943-945, mk/010-qemu-aarch64.mk:34-63). With ,accel=tcg QEMU emulates the CPU. The provisioning boot reads it from the environment as well (mk/010-qemu-aarch64.mk:15).Next: how the URL is found, per-distro quirks, Enterprise Linux, UEFI firmware, the six architectures, the users and the support matrix.
The tables are read from data/amazonlinux.ini, mk/050-amazonlinux-2.mk, mk/010-qemu-aarch64.mk, mk/010-qemu.mk and rulegen.py at the commit in garden.commit ("code"). The current file names were fetched from Amazon's SHA256SUMS lists on 21 November 2026 ("run"). Amazon Linux's support dates, package managers and default user are Amazon's own descriptions ("derived").
| System | Arch | Boot | Image directory | Amazon's file name | Local file name | CPU | aarch64 firmware | Section |
|---|---|---|---|---|---|---|---|---|
amazonlinux-cloud-2.x86_64 | x86_64 | bios | https://cdn.amazonlinux.com/os-images/latest/kvm/ | amzn2-kvm-VERSION-x86_64.xfs.gpt.qcow2 | amazonlinux-cloud-2-VERSION.x86_64.qcow2 | max | — | amazonlinux.ini:8-15 |
amazonlinux-cloud-2.aarch64 | aarch64 | efi | https://cdn.amazonlinux.com/os-images/latest/kvm-arm64/ | amzn2-kvm-VERSION-arm64.xfs.gpt.qcow2 | amazonlinux-cloud-2-VERSION.aarch64.qcow2 | neoverse-n1 | Fedora's EDK2 | amazonlinux.ini:17-24 |
amazonlinux-cloud-2023.x86_64 | x86_64 | efi | https://cdn.amazonlinux.com/al2023/os-images/latest/kvm/ | al2023-kvm-VERSION-kernel-K-x86_64.xfs.gpt.qcow2 | amazonlinux-cloud-2023-VERSION.x86_64.qcow2 | max | — | amazonlinux.ini:26-33 |
amazonlinux-cloud-2023.aarch64 | aarch64 | efi | https://cdn.amazonlinux.com/al2023/os-images/latest/kvm-arm64/ | al2023-kvm-VERSION-kernel-K-arm64.xfs.gpt.qcow2 | amazonlinux-cloud-2023-VERSION.aarch64.qcow2 | neoverse-n1 | Fedora's EDK2 | amazonlinux.ini:35-42 |
SHA256SUMS in the image directory, the same list the URLProgram reads; HASH NAME lines (rulegen.py:496-517).amzn2-kvm-2.0.20261120.0-x86_64.xfs.gpt.qcow2 and al2023-kvm-2023.12.20261120.0-kernel-6.1-x86_64.xfs.gpt.qcow2..url file is made again: after a change to image-garden.mk or .image-garden.mk, or once it is deleted. Older builds stay in $GARDEN_DL_DIR/amazonlinux/ until removed (bt-urlprogram).AMAZONLINUX_2_CLOUD_INIT_USER_DATA_TEMPLATE for release 2, the base template plus - shutdown --poweroff now (mk/050-amazonlinux-2.mk:4-8); the common template for 2023.root/root and amazonlinux/amazonlinux with passwordless sudo, not ec2-user (mk/010-qemu.mk:200-211). Host names amazonlinux-2 and amazonlinux-2023.snap setup script and GOPROXY only; yum and dnf are not proxied (mk/010-qemu.mk:127-180).QEMU_CPU_AARCH64=neoverse-n1 for both aarch64 systems' .qcow2 and .run (mk/050-amazonlinux-2.mk:10-11).GARDEN_AARCH64_FEDORA_EDK2_SYSTEMS (mk/010-qemu-aarch64.mk:134-145).QEMU_ACCEL_MACHINE_PROP=,accel=tcg (README.md:943-945).Each architecture has its own settings: the QEMU program, machine, CPU and default CPU count that go into the .run script.
mk/010-qemu-ARCH.mk starts with the program (QEMU_SYSTEM_X86_64, in the snap the snap's qemu-system-x86-64 app, else qemu-system-x86_64 from PATH), the machine, the CPU and the CPU count (mk/010-qemu-x86_64.mk:3-7, mk/010-qemu-aarch64.mk:4-6, mk/010-qemu-s390x.mk:4-6).image-garden.mk with the other mk/*.mk files (Makefile:48-50), and the run and provisioning rules of each system call that architecture's command line (rulegen.py:593-724)..run script builds the command as an array, with storage, firmware, RNG and network options too (mk/010-qemu-x86_64.mk:59-108).x86_64 q35, aarch64 virt,gic-version=max, riscv64 virt,acpi=off, loongarch64 virt, all with -cpu max; s390x s390-ccw-virtio with qemu, ppc64 pseries with power9.
| Architecture | Machine | CPU | Source |
|---|---|---|---|
| x86_64 | q35 (q35,smm=on for the +tpm systems) | max | mk/010-qemu-x86_64.mk:5-6 |
| aarch64 | virt,gic-version=max | max | mk/010-qemu-aarch64.mk:4-5 |
| riscv64 | virt,acpi=off | max | mk/010-qemu-riscv64.mk:4-5 |
| loongarch64 | virt | max | mk/010-qemu-loongarch64.mk:4-5 |
| s390x | s390-ccw-virtio | qemu | mk/010-qemu-s390x.mk:4-5 |
| ppc64 | pseries | power9 | mk/010-qemu-ppc64.mk:4-5 |
QEMU_CPU_AARCH64=neoverse-n1 for their .qcow2 and .run targets (mk/050-amazonlinux-2.mk:10-11).QEMU_CPU_X86_64=Haswell or newer for Rocky 10 and other RHEL 10 derivatives where max is not enough (README.md:677-681).max, gic-version=max and acpi=off mean is QEMU's documentation (derived).The .run script checks -accel help when it starts and uses accel=kvm:tcg or accel=tcg; QEMU_ACCEL_MACHINE_PROP overrides it. A /dev/kvm you cannot write gets a warning.
.run script computes default_qemu_accel_machine_prop when it runs: ,accel=kvm:tcg when QEMU -accel help lists kvm, else ,accel=tcg (mk/010-qemu-x86_64.mk:63); QEMU_ACCEL_MACHINE_PROP from the environment wins (mk/010-qemu-x86_64.mk:72) and is appended to -machine (mk/010-qemu-x86_64.mk:96). The provisioning boot uses the same test (mk/010-qemu-x86_64.mk:17). Every architecture's file does the same.kvm:tcg tells QEMU to try KVM and fall back to TCG (derived from QEMU's documentation).image-garden make and allocate run kvm_check: when /dev/kvm exists but is not writable, it prints a banner, then sudo chmod 666 /dev/kvm as advice in CI (CI set) or sudo usermod -aG kvm $LOGNAME elsewhere (image-garden:669-709).QEMU_ACCEL_MACHINE_PROP with the same default (README.md:943-945, image-garden.1:670-677).Without KVM, as for every foreign architecture, QEMU emulates the CPU with TCG, many times slower. Builds and tests of such systems need longer timeouts.
make all: "Cross-architecture emulation works but is slow and not recommended for routine use" (README.md:529-534)./dev/kvm, QEMU emulates the CPU (TCG), many times slower; GitLab.com's hosted runners do not give jobs /dev/kvm (README.md:778-785).The host's architecture gets -smp 4, every other one -smp 1, written into the .run script. QEMU_SMP_OPTION="-smp 2" overrides it for one run.
QEMU_SMP_<ARCH> = 1, such as mk/010-qemu-x86_64.mk:7; mk/010-qemu.mk sets QEMU_SMP_$(shell echo $(GARDEN_HOST_ARCH) | tr a-z- A-Z_) = 4, with the comment "Try to give the native arch some more cores as those are usually cheaper than tcg" (mk/010-qemu.mk:5-6)..run script records default_qemu_smp_option="-smp N" and uses QEMU_SMP_OPTION from the environment when set (mk/010-qemu-x86_64.mk:65, :74). A .run script made on one host keeps that host's count when copied elsewhere (derived).GARDEN_HOST_ARCH is uname -m with ppc64le named ppc64, so a POWER host raises QEMU_SMP_PPC64 (mk/000-garden.mk:14-17).QEMU_SMP_X86_64, _AARCH64, _RISCV64, _LOONGARCH64, _S390X and _PPC64, as "4 native, 1 cross-arch" (README.md:890-895), and its host tier table gives every host 4 vCPUs for its own architecture (README.md:389-396).QEMU_SMP_OPTION (the adhoc backend).mk/010-qemu-ARCH.mk sets QEMU_SMP_ARCH = 1; mk/010-qemu.mk, concatenated after them, sets the host's to 4, named from uname -m with ppc64le as ppc64. .image-garden.mk and the command line can override it.
image-garden.mk is data/000-systems.mk, then $(sort ...) of mk/*.mk, then the generated files (Makefile:48-50). Byte order puts mk/010-qemu-aarch64.mk and its siblings before mk/010-qemu.mk, as - (0x2d) sorts before . (0x2e).QEMU_SMP_X86_64 = 1 (mk/010-qemu-x86_64.mk:7) is a recursive assignment; the later = 4 replaces it (mk/010-qemu.mk:6). The .run recipe expands $(QEMU_SMP_X86_64) when it runs (mk/010-qemu-x86_64.mk:65), after every file is read.mk/999-local.mk includes the project's .image-garden.mk (mk/999-local.mk:4-5); a variable given on the make command line overrides assignments in makefiles (GNU make, derived). image-garden make passes its arguments to make (image-garden:982-993).GARDEN_HOST_ARCH, which is uname -m with ppc64le named ppc64 (mk/000-garden.mk:14-17). On a POWER host the variable set to 4 is QEMU_SMP_PPC64, the one the ppc64 .run rules read; the same name makes GARDEN_ARCH default to ppc64, so those systems join all:: too.Next: changing a .run script's defaults, runners without KVM, the support matrix, boot types, firmware and loongarch64.
Read in mk/010-qemu-*.mk, mk/010-qemu.mk and mk/050-amazonlinux-2.mk of image-garden at the tag in garden.commit ("code"). What the accelerator and CPU names do inside QEMU, and how the defaults play out on a given host, are derived from those rules and QEMU's documentation. Nothing was run for this page.
| Architecture | QEMU program | Machine | CPU | CPUs on this host / elsewhere | Boot types | Snap component |
|---|---|---|---|---|---|---|
| x86_64 | qemu-system-x86_64 | q35 | max | 4 / 1 | efi, bios | qemu-x86-64 |
| aarch64 | qemu-system-aarch64 | virt,gic-version=max | max (neoverse-n1 for Amazon Linux) | 4 / 1 | efi | qemu-aarch64 |
| riscv64 | qemu-system-riscv64 | virt,acpi=off | max | 4 / 1 | efi | qemu-riscv64 |
| loongarch64 | qemu-system-loongarch64 | virt | max | 4 / 1 | efi | qemu-loongarch64 |
| s390x | qemu-system-s390x | s390-ccw-virtio | qemu | 4 / 1 | platform | qemu-s390x |
| ppc64 | qemu-system-ppc64 | pseries | power9 | 4 / 1 (a ppc64le host counts as ppc64) | platform | qemu-ppc64 |
Every architecture: -m 2048, -nographic, a virtio-blk disk, -device virtio-rng-pci, and -netdev user with a virtio-net-pci card.
| Knob | Kind | Effect |
|---|---|---|
QEMU_ACCEL_MACHINE_PROP | environment, at run time | replaces ,accel=kvm:tcg or ,accel=tcg |
QEMU_SMP_OPTION | environment, at run time | replaces -smp N, such as QEMU_SMP_OPTION="-smp 2" |
QEMU_SMP_X86_64, _AARCH64, _RISCV64, _S390X, _PPC64, _LOONGARCH64 | make variable | the N written into new .run scripts |
QEMU_CPU_X86_64 and siblings | make variable | the -cpu model |
Make variables go on the command line (image-garden make QEMU_SMP_X86_64=2 SYSTEM.run) or in .image-garden.mk; a .run script that exists is not remade for a new value until a makefile it depends on changes. See the .run script.
One system, archlinux-cloud.x86_64: no release in the name, x86_64 only. image-garden make archlinux-cloud.x86_64.run builds it like any other.
data/archlinux.ini has [META] with Group=archlinux and Variant=cloud, and one section, [archlinux-cloud.x86_64] (archlinux.ini:4-12).Release= gets a name with no release part: group, variant and architecture. How names are put together is in system names.The image is images/latest/Arch-Linux-x86_64-cloudimg.qcow2 on Arch's mirror, a name with no date; its checksum is the one-line .SHA256 file next to it. x86_64 only, UEFI boot, and no release in the system name.
URL=https://geo.mirror.pkgbuild.com/images/latest/Arch-Linux-x86_64-cloudimg.qcow2, SHA256SUMS= the same URL with .SHA256 added, Arch=x86_64, Boot=efi, no Release= (archlinux.ini:8-12).Arch-Linux-x86_64-cloudimg.qcow2, in $GARDEN_DL_DIR/archlinux/ (rulegen.py:532-536, rulegen.py:782-792), and verified with download-with-sha256sums (rulegen.py:510-514).HASH Arch-Linux-x86_64-cloudimg.qcow2, the sha256sum format find_checksum_hash reads first (image-garden:75-91). The hash on the slide is the one served on 21 November 2026 (run with curl), shortened; it changes with every build.Arch-Linux-x86_64-cloudimg-20261115.625457.qcow2, with their own .SHA256 files (directory listing, run on 21 November 2026). image-garden uses the undated name.Boot=efi gives the x86_64 UEFI rules: a copy of the EDK2 code and a variable store per system (rulegen.py:593-610); see UEFI firmware per system.The common template: root/root and archlinux/archlinux with sudo, host name archlinux. pkgproxy adds its hosts line, the snap setup and GOPROXY; pacman is not set up.
mk/ file names Arch: ARCHLINUX_CLOUD_INIT_USER_DATA_TEMPLATE is not defined, so the picker falls back to CLOUD_INIT_USER_DATA_TEMPLATE, the common template (010-qemu.mk:285-298, 010-qemu.mk:249). The user-data passes the group, archlinux, as the second user (rulegen.py:467).root/root, and archlinux/archlinux in the users group with sudo: ["ALL=(ALL) NOPASSWD:ALL"] and bash (010-qemu.mk:200-211); --query reports both (010-qemu.mk:84-87). spread-demo logs in as archlinux/archlinux (spread-demo/spread.yaml:174-177).archlinux (010-qemu.mk:94-104, 010-qemu.mk:196)./etc/hosts line, PKGPROXY_BOOTCMD_SETUP (apt) only for debian and ubuntu, PKGPROXY_RUNCMD_SETUP (snap) for every group but alpine, and GOPROXY="http://pkgproxy:PORT/go,direct" appended to /etc/environment (010-qemu.mk:127-180). pkgproxy caches apt, the snap store and Go modules (proxy/README.md:40-48); nothing configures pacman.The cache keeps Arch-Linux-x86_64-cloudimg.qcow2 and its .sha256sums; later builds reuse them. Delete both from dl/archlinux/ to start from Arch's newest build.
FILE.sha256sums is missing, and the image only when FILE is missing; then it verifies the image against the kept checksum (image-garden:480-545). With a fixed name, nothing in the cache changes when Arch publishes a new build..image-garden.mk, X.url is newer than the cache link (rulegen.py:521-524), so the download rule runs again (rulegen.py:510-514), and the helper verifies the kept image without fetching it. The user-data is remade too, so the disk is provisioned again, on the same build (derived from the rules; see the overlay).image-garden make distclean removes the downloaded image, X.url and X.filename, and leaves FILE.sha256sums and FILE.lock (rulegen.py:486-492). Run with the helper from this tree and file:// URLs: with the old checksum file kept and a new image at the URL, the helper downloaded the image, failed the check, removed both files, fetched the new checksum file and downloaded the image a second time.Arch-Linux-x86_64-cloudimg.qcow2 and Arch-Linux-x86_64-cloudimg.qcow2.sha256sums from $GARDEN_DL_DIR/archlinux/ (~/.cache/image-garden/dl/archlinux/ for a native install, ~/snap/image-garden/common/cache/dl/archlinux/ for the snap); the next image-garden make downloads and provisions again.x86_64 only: emulated elsewhere, and left out of all there. No update at first boot: on an aged image, pacman -Syu before you install. Uncached by pkgproxy.
Arch=x86_64 is defined (archlinux.ini:11). all:: and fetch list a system only when GARDEN_ARCH is its architecture (rulegen.py:456-459, rulegen.py:480-484); image-garden make archlinux-cloud.x86_64.run still works on another host, with TCG (six architectures).package_update or package_upgrade key (010-qemu.mk:187-247). That pacman on a stale package database may ask the mirrors for files they no longer carry, and that pacman -Syu refreshes the database and upgrades first, is Arch's behaviour (derived).x86_64: [others] tests alpine-cloud-3 archlinux-cloud gentoo-cloud, "6.5 minutes on novigrad" (.gitlab-ci.yml:811-817); no aarch64 job lists Arch.Next: the support matrix, the users, pkgproxy family by family, the cache, downloads, and Gentoo.
Read in data/archlinux.ini, rulegen.py, mk/010-qemu.mk, the image-garden script, proxy/README.md, the README, the man page and .gitlab-ci.yml of image-garden at the commit in garden.commit ("code"). The checksum file's format, the dated builds next to the link and the image size were fetched from Arch's mirror on 21 November 2026, and the helper's double download with a stale checksum file was run with file:// URLs ("run"). Arch's own behaviour (rolling builds, pacman's package database, whether the image has snapd) is "derived".
| System | Arch | Boot | Release | Image | Checksum |
|---|---|---|---|---|---|
archlinux-cloud.x86_64 | x86_64 | efi | none | https://geo.mirror.pkgbuild.com/images/latest/Arch-Linux-x86_64-cloudimg.qcow2 | SHA256SUMS= the image URL + .SHA256 |
Source: archlinux.ini:4-12.
| Item | Value |
|---|---|
.url | the fixed URL, written by make (rulegen.py:521-524) |
| Local name | Arch-Linux-x86_64-cloudimg.qcow2, the URL's last part |
| Cache directory | $GARDEN_DL_DIR/archlinux/ |
| Checksum kept as | Arch-Linux-x86_64-cloudimg.qcow2.sha256sums |
| Checksum file format | one line, HASH NAME |
| Size | about 570 MB (run, 21 November 2026) |
| A newer build | delete the image and its .sha256sums from the cache |
| Item | Value |
|---|---|
| Template | the common template, CLOUD_INIT_USER_DATA_TEMPLATE (no Arch quirk) |
| Users | root/root; archlinux/archlinux, group users, passwordless sudo |
| Host name | archlinux |
--query | system.users.0 root, system.users.1 archlinux |
| pkgproxy | /etc/hosts line, snap setup script (runcmd), GOPROXY in /etc/environment; no apt step; pacman not set up |
| Updates | none asked for at first boot |
Sources: 010-qemu.mk:94-104, 010-qemu.mk:127-180, 010-qemu.mk:187-247, 010-qemu.mk:80-88.
| Item | Value |
|---|---|
| Hosts | x86_64 with KVM; elsewhere emulated (TCG), and left out of all and fetch |
| spread | archlinux-cloud with archlinux/archlinux in spread-demo (spread-demo/spread.yaml:174-177) |
| image-garden CI | x86_64: [others] with Alpine and Gentoo (.gitlab-ci.yml:811-817) |
The Boot key of a section is efi, bios or platform. It picks the generated rules, the firmware files and the QEMU options of the .run script.
Boot is an enum of platform, efi and bios (rulegen.py:17-20); which values a section may use depends on its architecture, and only s390x and ppc64 sections may leave the key out, getting platform (rulegen.py:300-333). data/README.md documents the key the same way (data/README.md:34-38).Arch=x86_64, Boot=efi, Release=24.04 (data/ubuntu.ini:237-242).x86_64 has efi and bios rules; aarch64, riscv64 and loongarch64 have efi rules; s390x and ppc64 boot platform. rulegen.py refuses every other combination, naming the section and the values to use.
BOOT_BY_ARCH lists the boot types each architecture has rules for, and load_boot checks every section against it while the INI file is read: no Boot on an architecture other than s390x and ppc64, or a value the architecture has no rules for, raises an error naming the section and the values to use (rulegen.py:300-333), which main reports as FILE: error: ... before printing any rule of that file (rulegen.py:753-757).ruleset_x86_64_efi or ruleset_x86_64_bios; aarch64, riscv64 and loongarch64 print their _efi ruleset; s390x and ppc64 print ruleset_s390x and ruleset_ppc64 (rulegen.py:804-821).X.run (the launcher) and X.qcow2 (the overlay and the provisioning boot), for example rulegen.py:593-610.GARDEN_SYSTEMS, all::, X.meta-data, X.user-data, clean::) and its download rules whatever its boot type (rulegen.py:777-803, rulegen.py:453-478).Image 'test-cloud.aarch64' has Boot=bios, which aarch64 does not support, use efi and Image 'test-cloud.s390x' has Boot=efi, which s390x does not support, use platform (tests/check-rulegen.sh:189-212)..RECIPEPREFIX=+ (rulegen.py:726-738); see rulegen.py.An efi system's .qcow2 and .run need X.efi-code.qcow2 and X.efi-vars.qcow2, attached as two pflash drives. A bios system has neither.
ruleset_x86_64_efi: X.run has X.efi-code.qcow2 and X.efi-vars.qcow2 as order-only prerequisites, and X.qcow2 has them as prerequisites, words 3 and 4 passed to the command line (rulegen.py:593-610). ruleset_x86_64_bios has neither (rulegen.py:612-629).-drive if=pflash,format=qcow2,unit=0,file=CODE,readonly=on -drive if=pflash,format=qcow2,unit=1,file=VARS (mk/010-qemu-x86_64.mk:13-26); the bios one has no firmware option (mk/010-qemu-x86_64.mk:27-39). In the .run script it is default_qemu_boot_firmware_option, which QEMU_BOOT_FIRMWARE_OPTION overrides (mk/010-qemu-x86_64.mk:67, :76).%.x86_64.efi-code.qcow2 and %.x86_64.efi-vars.qcow2 from the shared efi-code.x86_64.img and efi-vars.x86_64.img, converted with $(QEMU_IMG) (mk/010-qemu-x86_64.mk:324-329); the man page names them the same way (image-garden.1:159-167).s390x and ppc64 sections have no Boot key, so they are platform. Their .run scripts have no firmware options; QEMU's machine loads its own loader.
Boot key (data/ubuntu.ini:258-262); neither has any s390x or ppc64 section in the data (counted at the tag: 22). platform is the default only on these two architectures, and the only value rulegen.py accepts there (rulegen.py:300-333).s390-ccw.img for qemu-s390x, slof.bin, vof.bin and others for qemu-ppc64 (snap/snapcraft.yaml:380-410). That the machines load them by default is QEMU's behaviour (derived).rulegen.py --systems-meta writes _X_boot into data/000-systems.mk; define-instance picks its efi, bios or platform branch from it. Ubuntu Core's hand-written rules are all efi.
--systems-meta FILE, rulegen.py appends _X_group, _X_group_upper, _X_release, _X_arch and _X_boot for each system (rulegen.py:824-833); the Makefile builds data/000-systems.mk that way from every INI file (Makefile:60-64) and puts it first in image-garden.mk (Makefile:48-50).define-instance reads _$(base)_boot, and _$(base)_arch for the QEMU rules, and has an efi, a bios and a platform branch (mk/020-instances.mk:47-56, mk/020-instances.mk:81-146)..run and .qcow2 rules call the x86_64 and aarch64 EFI emitters and depend on the efi-code and efi-vars copies (mk/050-ubuntu-core.mk:23-53).A wrong value: has Boot='uefi', use one of platform, efi, bios. A missing one on x86_64: has no Boot=, use efi or bios for x86_64. Both stop the build, naming the file and the section.
load_boot reads Boot and checks it against BOOT_BY_ARCH: a value that is not a boot type fails in choice, which names the key, the value and the allowed ones; a missing Boot is accepted only on s390x and ppc64 (rulegen.py:288-297, rulegen.py:300-333). main turns the error into SystemExit(f"{filename}: error: {exc}") (rulegen.py:753-757), so the build of data/050-example.gen.mk fails (Makefile:57-58).bad-boot.ini: error: Image 'test-cloud.x86_64' has Boot='uefi', use one of platform, efi, bios and no-boot-x86_64.ini: error: Image 'test-cloud.x86_64' has no Boot=, use efi or bios for x86_64 (tests/check-rulegen.sh:189-200). On aarch64, riscv64 and loongarch64 the second ends use efi for aarch64 and so on..DELETE_ON_ERROR in the top-level Makefile removes the .gen.mk the failed rulegen.py left, so the next make tries again (Makefile:16-18).Boot is required for x86_64 (efi or bios) and for aarch64, riscv64 and loongarch64 (efi); s390x and ppc64 default to platform (data/README.md:34-38).example-cloud-1 and data/example.ini are made-up names.Next: UEFI firmware per system, the support matrix, named instances, the six machines, Secure Boot and the TPM, and the INI keys.
Read in rulegen.py, data/*.ini, mk/010-qemu-*.mk, mk/020-instances.mk and mk/050-ubuntu-core.mk of image-garden at the tag in garden.commit ("code"). The counts were taken from the INI files at the tag. The rulegen.py error messages are those tests/check-rulegen.sh expects (code). What QEMU's machines load without a firmware option is derived from QEMU's defaults.
| Arch | Boot=efi | Boot=bios | Boot=platform | Boot missing |
|---|---|---|---|---|
| x86_64 | ruleset_x86_64_efi | ruleset_x86_64_bios | error | error |
| aarch64 | ruleset_aarch64_efi | error | error | error |
| riscv64 | ruleset_riscv64_efi | error | error | error |
| loongarch64 | ruleset_loongarch64_efi | error | error | error |
| s390x | error | error | ruleset_s390x | ruleset_s390x |
| ppc64 | error | error | ruleset_ppc64 | ruleset_ppc64 |
"error" means rulegen.py stops with FILE: error: Image 'SECTION' has no Boot=, use VALUES for ARCH or ... has Boot=X, which ARCH does not support, use VALUES, and the .gen.mk is deleted (rulegen.py:300-333, rulegen.py:804-821). A value that is no boot type at all, such as uefi, gives has Boot='uefi', use one of platform, efi, bios.
| efi | bios | platform | |
|---|---|---|---|
| Per-system files | X.efi-code.qcow2, X.efi-vars.qcow2 | none | none |
| Shared files | efi-code.ARCH.img, efi-vars.ARCH.img | none | none |
| QEMU options | two -drive if=pflash, unit 0 read-only | none | none |
| Override | QEMU_BOOT_FIRMWARE_OPTION | ||
| Systems at the tag | 111 sections, plus every Ubuntu Core system | 6 x86_64 sections | the 22 s390x and ppc64 sections |
amazonlinux-cloud-2.x86_64, centos-cloud-9.x86_64, centos-cloud-10.x86_64, oracle-cloud-7.x86_64, oracle-cloud-8.x86_64, oracle-cloud-9.x86_64 (data/amazonlinux.ini:8-14, data/centos.ini:8-26, data/oracle.ini:10-35). Their aarch64 sections, where there are any, boot efi.
On grade dangerous snapd accepts a kernel or gadget you built. image-garden's +dangerous systems are Ubuntu Core 22, 24 and 26 with such a model.
22+dangerous, 24+dangerous and 26+dangerous (050-ubuntu-core.mk:4), on x86_64 and aarch64.880846b6 for this map.+dangerous images come from …/dangerous-stable/current/. Check with snap model --assertion | grep grade.
https://cdimage.ubuntu.com/ubuntu-core/R/dangerous-stable/current/, the plain ones from …/R/stable/current/ (050-ubuntu-core.mk:216-251). image-garden itself sets no grade and reads no model.grade: dangerous is derived from the channel's name and from image-garden's TPM test treating them alike; check it with snap model --assertion, which prints the raw model assertion (snapd cmd_model.go:83-93).grade header is signed, the default: see the model deck.checkGadgetOrKernel refuses an unasserted kernel or gadget over a signed one unless the grade is dangerous. system.kernel.dangerous-cmdline-append is used only on dangerous models.
checkGadgetOrKernel applies to snaps of type gadget and kernel (snapd check_snap.go:279-293) and refuses an unasserted replacement unless the grade is dangerous (snapd check_snap.go:318-320).system.kernel.dangerous-cmdline-append (snapd kernel.go:40) is appended to the kernel command line only when the model's grade is dangerous; system.kernel.cmdline-append is filtered by the gadget's allow list (snapd kcmdline.go:268-285).image-garden allocate ubuntu-core-24+dangerous.x86_64, scp -P PORT my-kernel.snap ubuntu@localhost:, sudo snap install --dangerous ./my-kernel.snap, reboot, uname -r.
image-garden allocate forwards 127.0.0.1:PORT to the guest's SSH port and prints the address (image-garden:1095-1206); Ubuntu Core's only login is ubuntu/ubuntu (050-ubuntu-core.mk:22-26).ubuntu-core-24-dangerous: the + of the system name becomes -, as a host name label allows no + (050-ubuntu-core.mk:141, 010-qemu.mk:94-97).SYSTEM.PORT.serial.log (image-garden:1153-1163).x1, and installing a kernel on Ubuntu Core ends with snapd restarting the device; see trying and packing a snap. Not run for this map.5123 and my-kernel_6.8_amd64.snap are examples.With -snapshot your install lives in a temporary overlay: it survives a guest reboot and goes away on discard. QEMU_SNAPSHOT_OPTION="" keeps changes.
${QEMU_SNAPSHOT_OPTION=-snapshot} (image-garden:1153-1163); discard kills the QEMU process by its pid file (image-garden:1221-1275).-snapshot: writes go to a temporary overlay that lasts as long as the QEMU process; a reboot inside the guest does not end the process, because the launcher passes no -no-reboot.QEMU_SNAPSHOT_OPTION="" makes allocate's changes persist in the system's .qcow2.Define UBUNTU_CORE_24+dangerous_CLOUD_INIT_USER_DATA_TEMPLATE in .image-garden.mk: $(UBUNTU_CORE_CLOUD_INIT_USER_DATA_TEMPLATE) first, then your runcmd lines.
UBUNTU_CORE and its release, such as 24+dangerous (050-ubuntu-core.mk:116), so UBUNTU_CORE_24+dangerous_CLOUD_INIT_USER_DATA_TEMPLATE is tried before UBUNTU_CORE_CLOUD_INIT_USER_DATA_TEMPLATE (010-qemu.mk:293-298).UBUNTU_CORE_CLOUD_INIT_USER_DATA_TEMPLATE is the base Ubuntu Core template, which ends with runcmd: lines, the last bringing eth0 back up (050-ubuntu-core.mk:131-179)..image-garden.mk, so editing it makes a new image (line 115).runcmd lines, and 10.0.2.2, the address under which QEMU's user networking shows the host to the guest (derived). A kernel installed during provisioning would finish on the next boot, after the provisioning boot powers off; check that in your own setup.Without storage-safety, a dangerous model means prefer-encrypted. ubuntu-core-24+dangerous+tpm encrypts ubuntu-data and ubuntu-save like +tpm.
storage-safety, snapd uses encrypted for grade secured and prefer-encrypted for the others (snapd model.go:1103-1122).ubuntu-core-24-plus-tpm, ubuntu-core-24-plus-dangerous-plus-tpm and their 26 equivalents and checks a TPM 2, Secure Boot and that the data and save mounts are on CRYPT-* devices (task.yaml:8-51).Next: on the snapd map the model, snap try and pack, and the kernel command line; here, allocate and Secure Boot and TPM.
Twelve systems: Debian 10 to 14 and sid, each on x86_64 and aarch64, all booting with EFI.
data/debian.ini starts with [META]: Group=debian, Variant=cloud (debian.ini:4-6), then twelve sections under the codename comments buster, bullseye, bookworm, trixie, forky and sid, each with Arch=x86_64 or Arch=aarch64, Boot=efi and Release= 10 to 14 or sid (debian.ini:8-103).debian-cloud-13.x86_64 as their example (README.md:557).…/images/cloud/trixie/daily/latest/debian-13-genericcloud-amd64-daily.qcow2, checked with SHA-512 against the SHA512SUMS list in the same directory.
https://cloud.debian.org/images/cloud/CODENAME/daily/latest/ with SHA512SUMS= the SHA512SUMS file of the same directory; the example is debian.ini:59-64.debian-10-generic-amd64-daily.qcow2 and debian-10-generic-arm64-daily.qcow2 (debian.ini:10-23); 11 to sid use genericcloud (debian.ini:27-103). That genericcloud is the smaller image for virtual machines and generic the one with drivers for real hardware is Debian's description (derived).SHA512SUMS= gets a rule that runs image-garden download-with-sha512sums (rulegen.py:498-502). The helper fetches the list to FILE.sha512sums, looks up the file's line, downloads the image (through pkgproxy first, by its hash, when there is one) and checks it with sha512sum --check; on a mismatch it deletes both and tries once more (image-garden:358-458). It reads HASH NAME, HASH *NAME and BSD-style lines (image-garden:75-92).map_to_debian_arch maps x86_64 to amd64 and aarch64 to arm64 (000-garden.mk:27-30), used for Ubuntu Core; the Debian URLs spell them out.x86_64 section whose URL has neither x86_64 nor amd64, and an aarch64 one without aarch64 or arm64 (rulegen.py:406-416).Users root/root and debian/debian, host name debian-13, apt sources over http. With pkgproxy: apt setup in bootcmd, snap setup in runcmd, GOPROXY.
root with plain_text_passwd: root and the group's user, debian, with the password debian, groups: users, sudo: ["ALL=(ALL) NOPASSWD:ALL"] and shell: /bin/bash (010-qemu.mk:200-211); the group is passed as the user name (rulegen.py:467).debian-13, debian-sid (010-qemu.mk:94-104, 010-qemu.mk:196).runcmd switches https:// to http:// in /etc/apt's *.list and *.sources files, when /etc/apt exists (010-qemu.mk:244).PKGPROXY_BOOTCMD_SETUP is apt for the groups debian and ubuntu, PKGPROXY_RUNCMD_SETUP is snap for every group but alpine (010-qemu.mk:127-130); GOPROXY="http://pkgproxy:PORT/go,direct" is appended to /etc/environment (010-qemu.mk:170-180).Acquire::http::Proxy to /etc/apt/apt.conf.d/99pkgproxy; the snap script writes a systemd drop-in for snapd "also where snapd is installed later", and restarts snapd where it is installed (proxy/README.md:166-184). Whether Debian's cloud images ship snapd is not in the source; Debian does not install it by default (derived).mk/ names Debian: it has no template of its own, and the apt hook in mk/050-ubuntu.mk emits nothing for the group debian (050-ubuntu.mk:14-28).The cached debian-13-genericcloud-amd64-daily.qcow2 is kept until you delete it. Remove it together with its .sha512sums file to get a newer daily image.
debian-13-genericcloud-amd64-daily.qcow2, in $(GARDEN_DL_DIR)/debian/, with the system's link debian-cloud-13.x86_64.qcow2 beside it (rulegen.py:498-502). The download directory is ~/.cache/image-garden/dl for a native install; see where image-garden keeps its files.FILE.sha512sums is missing, and the image only when FILE is missing; otherwise it only checks the image against the saved list (image-garden:373-458).distclean removes the downloaded image, the link, .url and .filename (rulegen.py:486-492), not FILE.sha512sums. With the old list kept, the next download asks pkgproxy for the old hash first (image-garden:281-308); a pkgproxy that kept the old image gives it back and the check passes. Without one, the new image fails the old hash, both files are deleted, and the second attempt fetches a fresh list and downloads again (image-garden:440-456). Worked out from the code (derived), not run.debian-13-genericcloud-amd64-daily.qcow2 and debian-13-genericcloud-amd64-daily.qcow2.sha512sums from the cache's debian/ directory, then run image-garden make debian-cloud-13.x86_64.run; the newer base image makes make prepare the disk again (derived).sid and 14 (testing) change daily. .sources files are rewritten to http like .list files. Debian 10 gets no archive rewrite: add one with EXTRA_CLOUD_INIT_APT_CONFIG if you need it.
debian-cloud-14 (forky) and debian-cloud-sid use daily images like the others (debian.ini:73-103); NEWS calls 14 "currently testing" (NEWS:131-132). That testing and unstable change daily and can break is Debian's release model (derived).runcmd rewrite covers *.sources as well as *.list (010-qemu.mk:244). That newer Debian releases use deb822 debian.sources files, and what such a file holds, is Debian's practice (derived); the drawing's file is an illustration.ubuntu and the releases on its list (050-ubuntu.mk:12-28); the common template calls the hook EXTRA_CLOUD_INIT_APT_CONFIG with the group and release for every system (010-qemu.mk:198), so a project can define it for debian and 10, keeping Ubuntu's block as the hooks deck shows.apt update before relying on it.Next: Ubuntu cloud images, the users, pkgproxy in the user-data, downloads, cloud-init hooks and the support matrix.
Read in data/debian.ini, rulegen.py, mk/010-qemu.mk, the image-garden script, proxy/README.md, README.md and NEWS of image-garden at the commit in garden.commit ("code"). What Debian's branches are, how its images differ and where its archived releases go is Debian's practice ("derived"). The cache behaviour of daily images is worked out from the download helper ("derived"). Nothing was run for this page.
The system name is debian-cloud-RELEASE.ARCH. Every system boots with efi: from its own copies of the host's EDK2 firmware (UEFI firmware per system).
| System | Codename | Architectures | Boot | Image | Host name |
|---|---|---|---|---|---|
debian-cloud-10 | buster | x86_64, aarch64 | efi | generic | debian-10 |
debian-cloud-11 | bullseye | x86_64, aarch64 | efi | genericcloud | debian-11 |
debian-cloud-12 | bookworm | x86_64, aarch64 | efi | genericcloud | debian-12 |
debian-cloud-13 | trixie | x86_64, aarch64 | efi | genericcloud | debian-13 |
debian-cloud-14 | forky | x86_64, aarch64 | efi | genericcloud | debian-14 |
debian-cloud-sid | sid | x86_64, aarch64 | efi | genericcloud | debian-sid |
Every image comes from Debian's daily builds; CODENAME is the codename in the table, R the release, DARCH Debian's name for the architecture (amd64 for x86_64, arm64 for aarch64), and KIND is generic for Debian 10 and genericcloud for the others.
image https://cloud.debian.org/images/cloud/CODENAME/daily/latest/debian-R-KIND-DARCH-daily.qcow2 checksum https://cloud.debian.org/images/cloud/CODENAME/daily/latest/SHA512SUMS
The checksum list is Debian's SHA512SUMS for the whole directory, checked with download-with-sha512sums. It is saved in the cache as FILE.sha512sums beside the image, and both keep the upstream name, which is the same every day: the first download stays until you remove both (The same name every day).
| What | On Debian | Source |
|---|---|---|
| Users | root/root; debian/debian in group users, passwordless sudo, bash | 010-qemu.mk:200-211 |
| Host name | debian-RELEASE, such as debian-13 | 010-qemu.mk:94-104 |
| SSH | password logins, root may log in | 010-qemu.mk:212-243 |
| apt sources | https:// becomes http:// in *.list and *.sources | 010-qemu.mk:244 |
| pkgproxy, bootcmd | /etc/hosts entry, reachability probe, pkgproxy's apt setup script | 010-qemu.mk:127-162 |
| pkgproxy, runcmd | /etc/hosts entry again, pkgproxy's snap setup script | 010-qemu.mk:164-168 |
| pkgproxy, files | GOPROXY appended to /etc/environment | 010-qemu.mk:170-180 |
| Distribution quirks | none: no mk/ file or template names Debian | per-distro quirks |
$ image-garden make debian-cloud-13.x86_64.run $ ./debian-cloud-13.x86_64.run --query $ image-garden allocate debian-cloud-13.x86_64
In spread.yaml the system is debian-cloud-13, with username: debian and password: debian, as in image-garden's spread demo (spread-demo/spread.yaml:42-60).
The groups almalinux, centos, oracle and rocky hold 23 systems, named GROUP-cloud-RELEASE.ARCH, such as rocky-cloud-9.x86_64.
Group=almalinux (almalinux.ini:4-6), Group=centos (centos.ini:4-6), Group=oracle (oracle.ini:4-6) and Group=rocky (rocky.ini:4-6), all Variant=cloud.[rocky-cloud-9.x86_64] is rocky.ini:22-27; [oracle-cloud-7.x86_64] is oracle.ini:10-15.AlmaLinux, CentOS and Rocky use latest images checked against a CHECKSUM list or a per-image .SHA256SUM file. Oracle's fixed builds have their SHA-256 hash written into image-garden itself.
https://repo.almalinux.org/almalinux/R/cloud/ARCH/images/AlmaLinux-R-GenericCloud-latest.ARCH.qcow2, checked against https://raw.repo.almalinux.org/almalinux/R/cloud/ARCH/images/CHECKSUM (almalinux.ini:8-48).https://cloud.centos.org/centos/R-stream/ARCH/images/CentOS-Stream-GenericCloud-R-latest.ARCH.qcow2, checked against the same URL plus .SHA256SUM (centos.ini:8-34).https://dl.rockylinux.org/pub/rocky/R/images/ARCH/Rocky-R-GenericCloud-Base.latest.ARCH.qcow2, checked against CHECKSUM in the same directory (rocky.ini:8-48).https://yum.oracle.com/templates/OracleLinux/OLR/uN/ARCH/, such as OL7U9_x86_64-kvm-b257.qcow2, each with a literal SHA256SUM=; the file's comment points at Oracle's templates page (oracle.ini:8-57). The hashes were added by hand (NEWS:510).SHA256SUMS= becomes download-with-sha256sums, SHA256SUM= becomes download-with-sha256sum with the hash on the command line (rulegen.py:62-71, rulegen.py:496-517). The list is fetched once and kept as FILE.sha256sums beside the image; an image already in the cache that matches it is not fetched again (image-garden:460-559)..url rule depends only on the makefiles, and the cached latest file keeps its name, so a newer build is fetched only after the cached file is removed, for example by image-garden make distclean (rulegen.py:520-524, derived from the rules).CHECKSUM has HASH NAME lines, Rocky's and CentOS's files SHA256 (NAME) = HASH lines; the helper reads both (image-garden:75-92). That Oracle lists checksums only on its web page is derived from the INI comment and the hand-copied hashes.AlmaLinux and Rocky: 8, 9, 10. CentOS Stream: 9, 10. Oracle: 7 to 10, with 7 on x86_64 only. All on x86_64 and aarch64, nothing else.
BIOS boot on x86_64 for centos-cloud-9, centos-cloud-10 and oracle-cloud-7 to 9: no firmware files. On aarch64, almalinux-cloud-8, oracle-cloud-8 and rocky-cloud-8 use Fedora's EDK2.
Boot=bios on x86_64: centos-cloud-9 and centos-cloud-10 (centos.ini:8-27), oracle-cloud-7, -8 and -9 (oracle.ini:10-36). Every other x86_64 section of the four files, and every aarch64 one, says Boot=efi.Boot=bios, rulegen.py writes the BIOS rules: the .run script needs only the .qcow2, and the command line has no -drive if=pflash (rulegen.py:612-631, rulegen.py:803-808, mk/010-qemu-x86_64.mk:27-39). QEMU then uses its default BIOS, SeaBIOS (derived).almalinux-cloud-8, oracle-cloud-8 and rocky-cloud-8 are in GARDEN_AARCH64_FEDORA_EDK2_SYSTEMS, with Fedora's EDK2 from the snap's qemu-aarch64 component or downloaded by checksum from image-garden's package registry (mk/010-qemu-aarch64.mk:114-167).Users root/root and GROUP/GROUP with passwordless sudo: almalinux, centos, oracle or rocky. Host name GROUP-RELEASE. No dnf or yum cache.
root/root and GROUP/GROUP with sudo: ["ALL=(ALL) NOPASSWD:ALL"] (mk/010-qemu.mk:200-211). None of the four groups has a quirk template.--query prints vm.memory_mb and the two users, root and the group (mk/010-qemu.mk:57-90, rulegen.py:596).GROUP-RELEASE, as rocky-9 (mk/010-qemu.mk:94-97).snap setup script and GOPROXY, not the apt script, and there is no script for dnf or yum (mk/010-qemu.mk:127-180).cloud-user, rocky or almalinux) come from their cloud-init configuration; a users: list without default replaces that user (derived, cloud-init behaviour).EL 10 needs x86-64-v3: the default -cpu max passes the host's through, or set QEMU_CPU_X86_64=Haswell. SELinux enforcing; CentOS Stream runs ahead of RHEL; Oracle 7 is old.
QEMU_CPU_X86_64=Haswell or newer if needed." (README.md:681); QEMU_CPU_X86_64 defaults to max (mk/010-qemu-x86_64.mk:6, README.md:896). It is a make variable, passed on the command line or set in .image-garden.mk (README.md:883-886); it is baked into the .run script and the provisioning boot when they are made.Next: Fedora, Amazon Linux, boot types, UEFI firmware, the users, downloads and the support matrix.
The tables are generated from data/almalinux.ini, data/centos.ini, data/oracle.ini and data/rocky.ini of image-garden at the commit in garden.commit ("code"). Users, host names, pkgproxy coverage and firmware are read in rulegen.py, mk/010-qemu.mk and mk/010-qemu-aarch64.mk ("code"). The checksum file formats were seen by fetching one of each on 21 November 2026 ("run"). What each distribution is, its default user and SELinux mode are the distributions' own descriptions ("derived").
Names are GROUP-cloud-RELEASE.ARCH. The checksum column names the checksum file, or the start of the hash image-garden carries itself.
| System | Arch | Boot | Image file | Checksum source | Section |
|---|---|---|---|---|---|
almalinux-cloud-8.x86_64 | x86_64 | efi | AlmaLinux-8-GenericCloud-latest.x86_64.qcow2 | CHECKSUM | almalinux.ini:8-13 |
almalinux-cloud-8.aarch64 | aarch64 | efi | AlmaLinux-8-GenericCloud-latest.aarch64.qcow2 | CHECKSUM | almalinux.ini:15-20 |
almalinux-cloud-9.x86_64 | x86_64 | efi | AlmaLinux-9-GenericCloud-latest.x86_64.qcow2 | CHECKSUM | almalinux.ini:22-27 |
almalinux-cloud-9.aarch64 | aarch64 | efi | AlmaLinux-9-GenericCloud-latest.aarch64.qcow2 | CHECKSUM | almalinux.ini:29-34 |
almalinux-cloud-10.x86_64 | x86_64 | efi | AlmaLinux-10-GenericCloud-latest.x86_64.qcow2 | CHECKSUM | almalinux.ini:36-41 |
almalinux-cloud-10.aarch64 | aarch64 | efi | AlmaLinux-10-GenericCloud-latest.aarch64.qcow2 | CHECKSUM | almalinux.ini:43-48 |
centos-cloud-9.x86_64 | x86_64 | bios | CentOS-Stream-GenericCloud-9-latest.x86_64.qcow2 | CentOS-Stream-GenericCloud-9-latest.x86_64.qcow2.SHA256SUM | centos.ini:8-13 |
centos-cloud-9.aarch64 | aarch64 | efi | CentOS-Stream-GenericCloud-9-latest.aarch64.qcow2 | CentOS-Stream-GenericCloud-9-latest.aarch64.qcow2.SHA256SUM | centos.ini:15-20 |
centos-cloud-10.x86_64 | x86_64 | bios | CentOS-Stream-GenericCloud-10-latest.x86_64.qcow2 | CentOS-Stream-GenericCloud-10-latest.x86_64.qcow2.SHA256SUM | centos.ini:22-27 |
centos-cloud-10.aarch64 | aarch64 | efi | CentOS-Stream-GenericCloud-10-latest.aarch64.qcow2 | CentOS-Stream-GenericCloud-10-latest.aarch64.qcow2.SHA256SUM | centos.ini:29-34 |
oracle-cloud-7.x86_64 | x86_64 | bios | OL7U9_x86_64-kvm-b257.qcow2 | SHA256SUM= 9e68a8fb682f… | oracle.ini:10-15 |
oracle-cloud-8.x86_64 | x86_64 | bios | OL8U10_x86_64-kvm-b287.qcow2 | SHA256SUM= cf9eb243b739… | oracle.ini:17-22 |
oracle-cloud-8.aarch64 | aarch64 | efi | OL8U10_aarch64-kvm-cloud-b170.qcow2 | SHA256SUM= 729114abf775… | oracle.ini:24-29 |
oracle-cloud-9.x86_64 | x86_64 | bios | OL9U8_x86_64-kvm-b293.qcow2 | SHA256SUM= b12103391327… | oracle.ini:31-36 |
oracle-cloud-9.aarch64 | aarch64 | efi | OL9U8_aarch64-kvm-cloud-b182.qcow2 | SHA256SUM= 4793c3ec49d9… | oracle.ini:38-43 |
oracle-cloud-10.x86_64 | x86_64 | efi | OL10U1_x86_64-kvm-b291.qcow2 | SHA256SUM= 8e59326c4bf7… | oracle.ini:45-50 |
oracle-cloud-10.aarch64 | aarch64 | efi | OL10U1_aarch64-kvm-cloud-b178.qcow2 | SHA256SUM= e203063e0e8b… | oracle.ini:52-57 |
rocky-cloud-8.x86_64 | x86_64 | efi | Rocky-8-GenericCloud-Base.latest.x86_64.qcow2 | CHECKSUM | rocky.ini:8-13 |
rocky-cloud-8.aarch64 | aarch64 | efi | Rocky-8-GenericCloud-Base.latest.aarch64.qcow2 | CHECKSUM | rocky.ini:15-20 |
rocky-cloud-9.x86_64 | x86_64 | efi | Rocky-9-GenericCloud-Base.latest.x86_64.qcow2 | CHECKSUM | rocky.ini:22-27 |
rocky-cloud-9.aarch64 | aarch64 | efi | Rocky-9-GenericCloud-Base.latest.aarch64.qcow2 | CHECKSUM | rocky.ini:29-34 |
rocky-cloud-10.x86_64 | x86_64 | efi | Rocky-10-GenericCloud-Base.latest.x86_64.qcow2 | CHECKSUM | rocky.ini:36-41 |
rocky-cloud-10.aarch64 | aarch64 | efi | Rocky-10-GenericCloud-Base.latest.aarch64.qcow2 | CHECKSUM | rocky.ini:43-48 |
| Group | User / password | Image directory | Checksum | Releases | aarch64 firmware |
|---|---|---|---|---|---|
almalinux | almalinux/almalinux | https://repo.almalinux.org/almalinux/R/cloud/ARCH/images/ | CHECKSUM on raw.repo.almalinux.org, HASH NAME lines | 8, 9, 10 | 8: Fedora's EDK2 |
centos | centos/centos | https://cloud.centos.org/centos/R-stream/ARCH/images/ | IMAGE.SHA256SUM per image, tag lines | 9, 10 | host EDK2 |
oracle | oracle/oracle | https://yum.oracle.com/templates/OracleLinux/OLR/uN/ARCH/ | literal SHA256SUM= in the INI | 7 (x86_64 only), 8, 9, 10 | 8: Fedora's EDK2 |
rocky | rocky/rocky | https://dl.rockylinux.org/pub/rocky/R/images/ARCH/ | CHECKSUM, tag lines | 8, 9, 10 | 8: Fedora's EDK2 |
root/root; the group user has passwordless sudo (mk/010-qemu.mk:200-211). Host names are GROUP-RELEASE, as rocky-9 (mk/010-qemu.mk:94-97).bios on x86_64 for CentOS 9 and 10 and Oracle 7, 8 and 9; efi everywhere else (sys-boot).almalinux-cloud-8, oracle-cloud-8 and rocky-cloud-8 on aarch64: GARDEN_AARCH64_FEDORA_EDK2_SYSTEMS (mk/010-qemu-aarch64.mk:134-145).snap setup script and GOPROXY only; dnf and yum are not proxied (mk/010-qemu.mk:127-180).$GARDEN_DL_DIR/GROUP/ under the image's own file name, the checksum list beside it as FILE.sha256sums (rt-cache). A latest file stays until it is removed.QEMU_CPU_X86_64 defaults to max (README.md:681).26 systems: Fedora 38 to 45. A system is named fedora-cloud-RELEASE.ARCH, such as fedora-cloud-42.x86_64.
data/fedora.ini starts with [META]: Group=fedora, Variant=cloud (fedora.ini:4-6), then 26 sections: releases 38 to 45 on x86_64 and aarch64, and 42 to 45 on riscv64 and s390x.[fedora-cloud-42.x86_64] (fedora.ini:64-69). The section name is the system name; rulegen.py reads Arch, Boot and Release from it (rulegen.py:114-127).Supported releases come from download.fedoraproject.org, end-of-life ones from dl.fedoraproject.org/pub/archive, RISC-V builds from pub/alt/risc-v and s390x from fedora-secondary. Each is checked against Fedora's CHECKSUM list, or a .sha256 file for riscv64.
https://download.fedoraproject.org/pub/fedora/linux/releases/R/Cloud/ARCH/images/ (fedora.ini:93-105); 38 to 42 use https://dl.fedoraproject.org/pub/archive/fedora/linux/releases/R/… (fedora.ini:8-76).https://dl.fedoraproject.org/pub/alt/risc-v/release/R/Cloud/riscv64/images/, such as Fedora-Cloud-Base-Generic-43-20260109.0.riscv64.qcow2, each with SHA256SUMS= pointing at the image URL plus .sha256 (fedora.ini:78-85, fedora.ini:107-112).https://dl.fedoraproject.org/pub/archive/fedora-secondary/… (fedora.ini:87-91), 43 to 45 from https://download.fedoraproject.org/pub/fedora-secondary/… (fedora.ini:114-118).SHA256SUMS= to Fedora's Fedora-Cloud-R-BUILD-ARCH-CHECKSUM file; rulegen.py turns that key into a download-with-sha256sums call (rulegen.py:496-517). The helper reads both HASH NAME lines and BSD tag lines, SHA256 (NAME) = HASH (image-garden:75-92)..sha256 file holds one HASH NAME line.download.fedoraproject.org is Fedora's mirror redirector and dl.fedoraproject.org its master server (derived, not in the source).x86_64 and aarch64 for 38 to 45; riscv64 and s390x for 42 to 45. efi on three architectures, platform on s390x. fedora-cloud-38.aarch64 boots with Fedora's EDK2.
.x86_64 and .aarch64 sections; .riscv64 and .s390x sections exist for 42, 43, 44 and 45 (data/fedora.ini). Only Ubuntu, with five, covers more architectures (the support matrix).Boot=efi; s390x sections have no Boot, which s390x accepts as platform, its only way (rulegen.py:300-333, fedora.ini:87-91).fedora-cloud-38 is in GARDEN_AARCH64_FEDORA_EDK2_SYSTEMS, the aarch64 systems "whose shim or grub predate what newer EDK2 enforces" (mk/010-qemu-aarch64.mk:114-145). The other Fedora releases use the host's EDK2.Users root/root and fedora/fedora with passwordless sudo; host name fedora-42. pkgproxy covers snapd and Go modules here, not dnf.
mk/050-fedora.mk: no FEDORA_…_CLOUD_INIT_USER_DATA_TEMPLATE is defined, so the picker falls back to the common CLOUD_INIT_USER_DATA_TEMPLATE (mk/010-qemu.mk:285-298).root/root and fedora/fedora in group users with sudo: ["ALL=(ALL) NOPASSWD:ALL"] (mk/010-qemu.mk:200-211).fedora-42 (mk/010-qemu.mk:94-97).debian and ubuntu, the snap script for every group but alpine (mk/010-qemu.mk:127-130, proxy/README.md:169-180). The snap script's drop-in also applies to a snapd installed later. GOPROXY goes into /etc/environment (mk/010-qemu.mk:170-180). No script configures dnf.https to http rewrite runs only where /etc/apt exists (mk/010-qemu.mk:244): nothing happens on Fedora.SELinux stays enforcing; packages arrive early; archived releases are frozen; riscv64 URLs name dated builds that may move.
pub/archive (fedora.ini:8-91); a release in Fedora's archive has reached its end of life and gets no updates (derived).Next: Enterprise Linux, the six architectures, UEFI firmware, the users, pkgproxy's user-data, downloads and the support matrix.
The table is generated from data/fedora.ini of image-garden at the commit in garden.commit ("code"). The users, host name and pkgproxy coverage are read in mk/010-qemu.mk and rulegen.py ("code"). The checksum file formats were seen by fetching one file of each kind on 21 November 2026 ("run"). Fedora's release cycle, its trees and SELinux's mode in the images are Fedora's practice ("derived").
The system name is fedora-cloud-RELEASE.ARCH. Boot platform means no firmware file (s390x). The checksum column names the checksum file, in the same directory as the image.
| System | Arch | Boot | Tree | Image file | Checksum source | Section |
|---|---|---|---|---|---|---|
fedora-cloud-38.x86_64 | x86_64 | efi | archive | Fedora-Cloud-Base-38-1.6.x86_64.qcow2 | Fedora-Cloud-38-1.6-x86_64-CHECKSUM | fedora.ini:8-13 |
fedora-cloud-38.aarch64 | aarch64 | efi | archive | Fedora-Cloud-Base-38-1.6.aarch64.qcow2 | Fedora-Cloud-38-1.6-aarch64-CHECKSUM | fedora.ini:15-20 |
fedora-cloud-39.x86_64 | x86_64 | efi | archive | Fedora-Cloud-Base-39-1.5.x86_64.qcow2 | Fedora-Cloud-39-1.5-x86_64-CHECKSUM | fedora.ini:22-27 |
fedora-cloud-39.aarch64 | aarch64 | efi | archive | Fedora-Cloud-Base-39-1.5.aarch64.qcow2 | Fedora-Cloud-39-1.5-aarch64-CHECKSUM | fedora.ini:29-34 |
fedora-cloud-40.x86_64 | x86_64 | efi | archive | Fedora-Cloud-Base-Generic.x86_64-40-1.14.qcow2 | Fedora-Cloud-40-1.14-x86_64-CHECKSUM | fedora.ini:36-41 |
fedora-cloud-40.aarch64 | aarch64 | efi | archive | Fedora-Cloud-Base-Generic.aarch64-40-1.14.qcow2 | Fedora-Cloud-40-1.14-aarch64-CHECKSUM | fedora.ini:43-48 |
fedora-cloud-41.x86_64 | x86_64 | efi | archive | Fedora-Cloud-Base-Generic-41-1.4.x86_64.qcow2 | Fedora-Cloud-41-1.4-x86_64-CHECKSUM | fedora.ini:50-55 |
fedora-cloud-41.aarch64 | aarch64 | efi | archive | Fedora-Cloud-Base-Generic-41-1.4.aarch64.qcow2 | Fedora-Cloud-41-1.4-aarch64-CHECKSUM | fedora.ini:57-62 |
fedora-cloud-42.x86_64 | x86_64 | efi | archive | Fedora-Cloud-Base-Generic-42-1.1.x86_64.qcow2 | Fedora-Cloud-42-1.1-x86_64-CHECKSUM | fedora.ini:64-69 |
fedora-cloud-42.aarch64 | aarch64 | efi | archive | Fedora-Cloud-Base-Generic-42-1.1.aarch64.qcow2 | Fedora-Cloud-42-1.1-aarch64-CHECKSUM | fedora.ini:71-76 |
fedora-cloud-42.riscv64 | riscv64 | efi | alt/risc-v | Fedora-Cloud-Base-Generic-42.20250911-2251ba41cdd3.riscv64.qcow2 | Fedora-Cloud-Base-Generic-42.20250911-2251ba41cdd3.riscv64.qcow2.sha256 | fedora.ini:80-85 |
fedora-cloud-42.s390x | s390x | platform | archive, secondary | Fedora-Cloud-Base-Generic-42-1.1.s390x.qcow2 | Fedora-Cloud-42-1.1-s390x-CHECKSUM | fedora.ini:87-91 |
fedora-cloud-43.x86_64 | x86_64 | efi | current | Fedora-Cloud-Base-Generic-43-1.6.x86_64.qcow2 | Fedora-Cloud-43-1.6-x86_64-CHECKSUM | fedora.ini:93-98 |
fedora-cloud-43.aarch64 | aarch64 | efi | current | Fedora-Cloud-Base-Generic-43-1.6.aarch64.qcow2 | Fedora-Cloud-43-1.6-aarch64-CHECKSUM | fedora.ini:100-105 |
fedora-cloud-43.riscv64 | riscv64 | efi | alt/risc-v | Fedora-Cloud-Base-Generic-43-20260109.0.riscv64.qcow2 | Fedora-Cloud-Base-Generic-43-20260109.0.riscv64.qcow2.sha256 | fedora.ini:107-112 |
fedora-cloud-43.s390x | s390x | platform | secondary | Fedora-Cloud-Base-Generic-43-1.6.s390x.qcow2 | Fedora-Cloud-43-1.6-s390x-CHECKSUM | fedora.ini:114-118 |
fedora-cloud-44.x86_64 | x86_64 | efi | current | Fedora-Cloud-Base-Generic-44-1.7.x86_64.qcow2 | Fedora-Cloud-44-1.7-x86_64-CHECKSUM | fedora.ini:120-125 |
fedora-cloud-44.aarch64 | aarch64 | efi | current | Fedora-Cloud-Base-Generic-44-1.7.aarch64.qcow2 | Fedora-Cloud-44-1.7-aarch64-CHECKSUM | fedora.ini:127-132 |
fedora-cloud-44.riscv64 | riscv64 | efi | alt/risc-v | Fedora-Cloud-Base-Generic-44-20260604.0.riscv64.qcow2 | Fedora-Cloud-Base-Generic-44-20260604.0.riscv64.qcow2.sha256 | fedora.ini:134-139 |
fedora-cloud-44.s390x | s390x | platform | secondary | Fedora-Cloud-Base-Generic-44-1.7.s390x.qcow2 | Fedora-Cloud-44-1.7-s390x-CHECKSUM | fedora.ini:141-145 |
fedora-cloud-45.x86_64 | x86_64 | efi | current | Fedora-Cloud-Base-Generic-45-1.4.x86_64.qcow2 | Fedora-Cloud-45-1.4-x86_64-CHECKSUM | fedora.ini:147-152 |
fedora-cloud-45.aarch64 | aarch64 | efi | current | Fedora-Cloud-Base-Generic-45-1.4.aarch64.qcow2 | Fedora-Cloud-45-1.4-aarch64-CHECKSUM | fedora.ini:154-159 |
fedora-cloud-45.riscv64 | riscv64 | efi | alt/risc-v | Fedora-Cloud-Base-Generic-45-20261022.0.riscv64.qcow2 | Fedora-Cloud-Base-Generic-45-20261022.0.riscv64.qcow2.sha256 | fedora.ini:161-166 |
fedora-cloud-45.s390x | s390x | platform | secondary | Fedora-Cloud-Base-Generic-45-1.4.s390x.qcow2 | Fedora-Cloud-45-1.4-s390x-CHECKSUM | fedora.ini:168-172 |
| Tree | Releases | URL directory |
|---|---|---|
| current | 43 to 45, x86_64 and aarch64 | https://download.fedoraproject.org/pub/fedora/linux/releases/R/Cloud/ARCH/images/ |
| archive | 38 to 42, x86_64 and aarch64 | https://dl.fedoraproject.org/pub/archive/fedora/linux/releases/R/Cloud/ARCH/images/ |
| alt/risc-v | 42 to 45, riscv64 | https://dl.fedoraproject.org/pub/alt/risc-v/release/R/Cloud/riscv64/images/ |
| archive, secondary | 42, s390x | https://dl.fedoraproject.org/pub/archive/fedora-secondary/releases/42/Cloud/s390x/images/ |
| secondary | 43 to 45, s390x | https://download.fedoraproject.org/pub/fedora-secondary/releases/R/Cloud/s390x/images/ |
Fedora-Cloud-R-BUILD-ARCH-CHECKSUM (tag lines, SHA256 (NAME) = HASH, PGP-signed; the signature is not checked) beside x86_64, aarch64 and s390x images; IMAGE.qcow2.sha256 (HASH NAME) beside riscv64 images. Both are read by download-with-sha256sums (image-garden:75-92, rulegen.py:496-517).$GARDEN_DL_DIR/fedora/ under the image's own file name, with a link named after the system (rt-cache).root/root and fedora/fedora, the latter with passwordless sudo (mk/010-qemu.mk:200-211, rulegen.py:467). --query prints both as system.users.0 and system.users.1 (mk/010-qemu.mk:79-88).fedora-R, as fedora-42 (mk/010-qemu.mk:94-97).snap setup script and GOPROXY in /etc/environment; no apt script (Debian and Ubuntu only) and no dnf script (mk/010-qemu.mk:127-180). The image download itself can still come through a pkgproxy on the host (px-downloads).q35, -cpu max, OVMF from the host or the snap (sys-firmware).virt, -cpu max; fedora-cloud-38 uses Fedora's EDK2 from GARDEN_AARCH64_FEDORA_EDK2_SYSTEMS (mk/010-qemu-aarch64.mk:134-145).virt,acpi=off, EDK2; s390x: s390-ccw-virtio, no firmware files (sys-arches).efi-code.x86_64.img and efi-vars.x86_64.img are copied once from the host; each efi system gets X.efi-code.qcow2, attached read-only, and X.efi-vars.qcow2, writable.
efi-code.x86_64.img and efi-vars.x86_64.img are copied with cp --preserve=timestamps from the first file found (mk/010-qemu-x86_64.mk:316-322); %.x86_64.efi-code.qcow2 and %.x86_64.efi-vars.qcow2 convert them with $(QEMU_IMG) convert -f raw -O qcow2, the qemu-img that QEMU_IMG names (mk/010-qemu-x86_64.mk:324-329). Every UEFI architecture's file has the same rules..run script's default firmware option: unit 0 readonly=on, unit 1 writable (mk/010-qemu-x86_64.mk:67).SYSTEM.ARCH.efi-code.qcow2 is a copy of efi-code.ARCH.img, SYSTEM.ARCH.efi-vars.qcow2 holds the current variables; ten shared firmware files (README.md:827-828, README.md:839-852)..image-garden/ or the project directory (see the cache deck).$SYSTEM.$ARCH.efi-code.qcow2, a copy of efi-code.$ARCH.img, and $SYSTEM.$ARCH.efi-vars.qcow2, made from efi-vars.$ARCH.img (image-garden.1:159-167).QEMU_EDK2_CODE_ARCH and QEMU_EDK2_VARS_ARCH list distribution paths, then the snap component's file, then $GARDEN_ARCH_PREFIX/share/qemu. The first file that exists is copied; riscv64 copies are truncated to 32 MiB.
QEMU_EDK2_CODE_X86_64 and QEMU_EDK2_VARS_X86_64, "default location on most Debian/Ubuntu systems, Arch and openSUSE", then the snap's qemu-x86-64/share/qemu/edk2-x86_64-code.fd and edk2-i386-vars.fd, then $GARDEN_X86_64_PREFIX/share/qemu/… (mk/010-qemu-x86_64.mk:260-280). Which distribution uses which path is derived from that comment.$(firstword $(wildcard LIST)) picks the first existing file for the code and, separately, for the variables (mk/010-qemu-x86_64.mk:318-322)./usr/share/AAVMF/AAVMF_CODE.fd, /usr/share/qemu/aavmf-aarch64-code.bin, then the snap's edk2-aarch64-code.fd and edk2-arm-vars.fd, then the prefix (mk/010-qemu-aarch64.mk:76-91)./usr/share/qemu-efi-riscv64/RISCV_VIRT_CODE.fd, /usr/share/edk2/riscv/RISCV_VIRT_CODE.fd, /usr/share/qemu/ovmf-riscv64-code.bin, the snap's, the prefix's; both copies get truncate --size 32MiB (mk/010-qemu-riscv64.mk:75-110).?=, so a project can replace it in .image-garden.mk or on the make command line (derived from GNU make).Ten aarch64 systems, listed in GARDEN_AARCH64_FEDORA_EDK2_SYSTEMS, use Fedora's EDK2; ubuntu-cloud-14.04 and 16.04 use Ubuntu's EDK2 from 22.04. Both come from the snap's qemu-aarch64 component or a checksummed download.
EDK2_AARCH64_FEDORA: from 2023 EDK2 marks memory that boot loaders load data into as not executable and offers the EFI memory attribute protocol, which shim 15.6 and 15.7 misuse; with Debian's and Ubuntu's EDK2 those systems stop with "Synchronous Exception" (mk/010-qemu-aarch64.mk:114-127).GARDEN_AARCH64_FEDORA_EDK2_SYSTEMS ?= almalinux-cloud-8, amazonlinux-cloud-2, amazonlinux-cloud-2023, fedora-cloud-38, opensuse-cloud-15.4, opensuse-cloud-15.5, oracle-cloud-8, rocky-cloud-8, ubuntu-core-22, ubuntu-core-22+dangerous; their .aarch64.efi-code.qcow2 and .efi-vars.qcow2 are copies of QEMU_EFI-pflash.qcow2 and vars-template-pflash.qcow2 (mk/010-qemu-aarch64.mk:134-167).GARDEN_AARCH64_JAMMY_EDK2_SYSTEMS ?= ubuntu-cloud-14.04, ubuntu-cloud-16.04: their 4.4 kernel gives up when the memory map changes while it exits boot services ("Failed to update FDT and exit boot services" under Fedora's EDK2); Ubuntu's EDK2 2022.02 boots them (mk/010-qemu-aarch64.mk:169-213).share/qemu/edk2-fedora, share/qemu/edk2-jammy); elsewhere download-with-sha256sum fetches them into $(GARDEN_DL_DIR)/edk2-aarch64-fedora/VERSION and edk2-aarch64-jammy/VERSION from the project's GitLab generic packages (mk/010-qemu-aarch64.mk:128-161, :182-207). The pinned builds are EDK2_AARCH64_FEDORA = 20260812-10.fc45 and EDK2_AARCH64_JAMMY = 2022.02-3ubuntu0.22.04.7.?=, a project can add a system to either list (derived).OVMF_CODE_4M.secboot.fd with OVMF_VARS_4M.ms.fd, as a pair, become efi-secboot-code.x86_64.img and efi-secboot-vars.x86_64.img for the +tpm systems only.
QEMU_EDK2_SECBOOT_CODE_X86_64 ?= /usr/share/OVMF/OVMF_CODE_4M.secboot.fd and QEMU_EDK2_SECBOOT_VARS_X86_64 ?= /usr/share/OVMF/OVMF_VARS_4M.ms.fd, plus the snap component's share/ovmf copies; QEMU_EDK2_SECBOOT_PAIR_X86_64 joins the Nth entries and takes the first pair where both exist (mk/010-qemu-x86_64.mk:282-296).efi-secboot-code.x86_64.img and efi-secboot-vars.x86_64.img copy the pair or print "please install x86_64 edk2 firmware with Secure Boot and Microsoft keys (the ovmf package) - not in … with …" and fail; the check runs only when such a system is made (mk/010-qemu-x86_64.mk:298-308)..efi-code.qcow2 and .efi-vars.qcow2 are converted from them, and their .run and .qcow2 use QEMU_SYSTEM_X86_64_MACHINE = q35,smm=on (mk/050-ubuntu-core.mk:55-61); "Secure Boot firmware keeps its variables in flash that only SMM may write" (mk/010-qemu-x86_64.mk:134-135).ovmf-x86-64 part stages the pair from Ubuntu's ovmf-generic package into the qemu-x86-64 component (snap/snapcraft.yaml:645-665).GARDEN_X86_64_PREFIX, _AARCH64_, _RISCV64_ and _LOONGARCH64_PREFIX append PREFIX/share/qemu/edk2-* to the search lists. The container sets them to /usr/local.
$(GARDEN_ARCH_PREFIX)/share/qemu/edk2-…-code.fd and the matching vars file when the variable is set (mk/010-qemu-x86_64.mk:277-280, mk/010-qemu-aarch64.mk:88-91, mk/010-qemu-riscv64.mk:89-92, mk/010-qemu-loongarch64.mk:91-94). The Secure Boot lists have no prefix entry./usr/local and sets the four prefixes (Dockerfile:98-102); the README names the same four (README.md:360-363).ovmf and swtpm (Dockerfile:78-91). That Ubuntu's ovmf package has /usr/share/OVMF/OVMF_CODE_4M.fd, which comes before the prefix in the x86_64 list, is derived from the package's contents, not run.A missing firmware gives please install x86_64 edk2 firmware - not in … on every make. In the snap a missing component gives install qemu-x86-64 component to use x86_64 emulation.
efi-code.x86_64.img is $(or $(firstword $(wildcard …)),$(warning please install x86_64 edk2 firmware - not in …)) (mk/010-qemu-x86_64.mk:318-322). GNU make expands prerequisites when it reads the rule, so the warning appears on every run that reads image-garden.mk, once for each architecture whose list finds nothing (derived from GNU make).cp --preserve=timestamps $< $@ gets one argument; the cp message on the slide is GNU coreutils' (derived, not run).efi-code.ARCH.img has check-qemu-ARCH-component as an order-only prerequisite, which runs ENSURE_QEMU_SNAP_COMPONENT: "install qemu-x86-64 component to use x86_64 emulation" (mk/010-qemu-x86_64.mk:310-316, mk/010-qemu.mk:50-55).Next: boot types, Secure Boot and the TPM, the six machines, the target chain, the container in CI and the snap.
Read in mk/010-qemu-x86_64.mk, mk/010-qemu-aarch64.mk, mk/010-qemu-riscv64.mk, mk/010-qemu-loongarch64.mk, mk/050-ubuntu-core.mk, snap/snapcraft.yaml, the Dockerfile and the man page of image-garden at the tag in garden.commit ("code"). Which distribution installs which path, and what make and cp print when nothing is found, are derived. Nothing was run for this page.
The first existing file of each list is copied. Lists are tried in this order: the paths below, then the snap's component (in the snap), then $GARDEN_ARCH_PREFIX/share/qemu/ (when set).
| Arch | Code | Variables | Snap component file | Prefix file |
|---|---|---|---|---|
| x86_64 | /usr/share/OVMF/OVMF_CODE.fd, /usr/share/OVMF/OVMF_CODE_4M.fd, /usr/share/ovmf/x64/OVMF_CODE.4m.fd, /usr/share/qemu/ovmf-x86_64-4m-code.bin | the matching VARS paths | qemu-x86-64/share/qemu/edk2-x86_64-code.fd, edk2-i386-vars.fd | same names |
| aarch64 | /usr/share/AAVMF/AAVMF_CODE.fd, /usr/share/qemu/aavmf-aarch64-code.bin | the matching VARS paths | qemu-aarch64/share/qemu/edk2-aarch64-code.fd, edk2-arm-vars.fd | same names |
| riscv64 | /usr/share/qemu-efi-riscv64/RISCV_VIRT_CODE.fd, /usr/share/edk2/riscv/RISCV_VIRT_CODE.fd, /usr/share/qemu/ovmf-riscv64-code.bin | the matching VARS paths | qemu-riscv64/share/qemu/edk2-riscv-code.fd, edk2-riscv-vars.fd | same names |
| loongarch64 | /usr/share/qemu-efi-loongarch64/QEMU_EFI.fd, /usr/share/edk2/loongarch64/QEMU_EFI.fd | QEMU_VARS.fd in the same directories | qemu-loongarch64/share/qemu/edk2-loongarch64-code.fd, -vars.fd | same names |
| x86_64 Secure Boot | /usr/share/OVMF/OVMF_CODE_4M.secboot.fd | /usr/share/OVMF/OVMF_VARS_4M.ms.fd | qemu-x86-64/share/ovmf/ with the same names | none |
| File | Made from | Used by |
|---|---|---|
efi-code.ARCH.img, efi-vars.ARCH.img | the first file of each list | every efi system of that architecture |
efi-secboot-code.x86_64.img, efi-secboot-vars.x86_64.img | the first complete Secure Boot pair | the four +tpm systems |
X.efi-code.qcow2 | $(QEMU_IMG) convert of the code | pflash unit 0, read-only |
X.efi-vars.qcow2 | $(QEMU_IMG) convert of the variables | pflash unit 1, writable |
$(GARDEN_DL_DIR)/edk2-aarch64-fedora/VERSION/ | download, SHA-256 checked | ten aarch64 systems (outside the snap) |
$(GARDEN_DL_DIR)/edk2-aarch64-jammy/VERSION/ | download, SHA-256 checked | ubuntu-cloud-14.04 and 16.04 on aarch64 (outside the snap) |
| Variable | Kind | Effect |
|---|---|---|
QEMU_EDK2_CODE_ARCH, QEMU_EDK2_VARS_ARCH | make, ?= | replace a search list |
QEMU_EDK2_SECBOOT_CODE_X86_64, QEMU_EDK2_SECBOOT_VARS_X86_64 | make, ?= | replace the Secure Boot lists |
GARDEN_AARCH64_FEDORA_EDK2_SYSTEMS, GARDEN_AARCH64_JAMMY_EDK2_SYSTEMS | make, ?= | which aarch64 systems use the older builds |
GARDEN_X86_64_PREFIX, GARDEN_AARCH64_PREFIX, GARDEN_RISCV64_PREFIX, GARDEN_LOONGARCH64_PREFIX | environment | append a self-built QEMU's EDK2 to the lists |
QEMU_BOOT_FIRMWARE_OPTION | environment, at run time | replaces both pflash drives of a .run script |
QEMU_IMG | make | the qemu-img that converts the firmware copies to qcow2 |
Two systems, gentoo-cloud.x86_64 and gentoo-cloud.aarch64, rolling, with no release. Its URL comes from a program, its image is large, its SSH is switched on by hand, and upstream spread cannot connect.
data/gentoo.ini: Group=gentoo, Variant=cloud, sections [gentoo-cloud.x86_64] and [gentoo-cloud.aarch64], each with URLProgram, URLPattern, LocalFilenameTemplate, SHA256SUMS=@URL@.sha256 and Boot=efi, and no Release= (gentoo.ini:4-22).mk/050.gentoo.mk (050.gentoo.mk:4-8); the release notes that added Gentoo say spread's Go SSH client "is unable to connect to a started instance" (NEWS:610-612).archlinux-cloud and opencloudos-cloud-9 but no gentoo-cloud (image-garden.1:211-245).A program reads latest-di-amd64-cloudinit.txt and turns line six into the image's address; the image is cached as gentoo-cloud-STAMP.x86_64.qcow2 and checked against the .sha256 file next to it.
URLProgram=$(CURL) https://distfiles.gentoo.org/releases/amd64/autobuilds/latest-di-amd64-cloudinit.txt | awk 'NR==6 { print "https://distfiles.gentoo.org/releases/amd64/autobuilds/"$$1 }', URLPattern=…/autobuilds/([0-9]{8}T[0-9]{6}Z)/di-amd64-cloudinit-[0-9]{8}T[0-9]{6}Z\.qcow2$, LocalFilenameTemplate=gentoo-cloud-@1.x86_64.qcow2 (gentoo.ini:8-14). aarch64 is the same with arm64 and .aarch64 (gentoo.ini:16-22).$GARDEN_DL_DIR/gentoo/gentoo-cloud.x86_64.url (rulegen.py:526-530) and the cached name to gentoo-cloud.x86_64.filename (rulegen.py:546-591).IMAGE.qcow2.sha256, is also PGP-signed and holds HASH di-amd64-cloudinit-STAMP.qcow2. The helper looks for the cached name first and, not finding it, for the URL's last part (image-garden:508-515). Checking against it came with "Gentoo images are now verified against the SHA-256 checksum published next to each image" (NEWS:161-164).image-garden defines GENTOO_CLOUD_INIT_USER_DATA_TEMPLATE: the base template plus systemctl enable --now sshd.service. A template of your own for Gentoo must keep that line.
mk/050.gentoo.mk: "Gentoo ships ssh disabled out of the box, so enable it.", then GENTOO_CLOUD_INIT_USER_DATA_TEMPLATE = $(BASE_CLOUD_INIT_USER_DATA_TEMPLATE) plus - systemctl enable --now sshd.service (050.gentoo.mk:1-8). The extra line lands after the base template's last runcmd item, touch /etc/cloud/cloud-init.disabled (010-qemu.mk:238-247).GENTOO_), then CLOUD_INIT_USER_DATA_TEMPLATE (010-qemu.mk:285-298); the user-data asks it with the upper-case group and the empty release (rulegen.py:467).050.gentoo.mk); the build takes every mk/*.mk (see per-distribution quirks).CLOUD_INIT_USER_DATA_TEMPLATE does not change Gentoo, whose template starts from BASE_CLOUD_INIT_USER_DATA_TEMPLATE.root/root and gentoo/gentoo with sudo, host name gentoo. pkgproxy adds its hosts line, the snap setup and GOPROXY; Portage is not set up.
root/root, and gentoo/gentoo in the users group with sudo: ["ALL=(ALL) NOPASSWD:ALL"] and bash (010-qemu.mk:200-211). Whether the image ships sudo is not in the tree. --query reports both (010-qemu.mk:84-87); spread-demo names gentoo/gentoo (spread-demo/spread.yaml:237-240).local-hostname: gentoo, the group with no release (010-qemu.mk:94-104)./etc/hosts line, the snap script from runcmd (every group but alpine), no apt script (only debian and ubuntu), and GOPROXY in /etc/environment (010-qemu.mk:127-180). pkgproxy serves apt, the snap store and Go modules (proxy/README.md:40-48); nothing configures Portage.emerge fetches distfiles from Gentoo's mirrors is Portage's behaviour (derived).Over a gigabyte. A makefile change asks for the latest build again; a new one is downloaded beside the old. The question bypasses pkgproxy; after a failed one, delete gentoo-cloud.ARCH.url in the cache. Upstream spread cannot connect.
latest-di-amd64-cloudinit.txt gave 1205665792 bytes for the x86_64 image, and Arch's mirror 569933312 bytes for its image (run with curl on 21 November 2026). Both change with every build.X.url depends on $(MAKEFILE_LIST), which includes .image-garden.mk (rulegen.py:526-530); a new URL gives a new cached name, and the system's link in the cache moves to it (rulegen.py:510-514). distclean removes only the file the .filename names (rulegen.py:486-492), so older builds stay until you delete them. See when upstream moves on.$(CURL), image-garden's curl, straight at distfiles.gentoo.org (gentoo.ini:9, 000-garden.mk:21); only the image and checksum downloads ask pkgproxy first (image-garden:195-308).CURL=false with an image-garden.mk built from this tree: the recipe's pipeline ends in awk, so make wrote an empty .url and went on; the filename rule printed "URL for gentoo-cloud.x86_64 does not match URLPattern" but ends in tee, so it wrote an empty .filename and make exited 0. A second make found both files up to date, and the download then failed with "curl: (3) URL rejected: No host part in the URL". Deleting $GARDEN_DL_DIR/gentoo/gentoo-cloud.ARCH.url (and .filename), or touching .image-garden.mk, makes make ask again.gentoo-cloud: "Spread cannot connect to sshd 10 in gentoo", with a link to spread issue 243 (spread-demo/Makefile:7-13). The snap also carries spread-plus, a fork of spread (snap/snapcraft.yaml:46-58); whether it connects is not stated in the tree.x86_64: [others] has gentoo-cloud (.gitlab-ci.yml:811-817); its spread run goes through spread-demo's make spread-gentoo-cloud, which only prints that message (tests/ci/run-systems.sh:104-116). aarch64: [others] has only alpine-cloud-3 (.gitlab-ci.yml:889-895).Next: how the program finds the build, checksums, per-distribution quirks, SSH logins, spread, and Arch Linux.
Read in data/gentoo.ini, mk/050.gentoo.mk, mk/010-qemu.mk, rulegen.py, the image-garden script, spread-demo/, the README, NEWS, the man page and .gitlab-ci.yml of image-garden at the commit in garden.commit ("code"). Gentoo's latest-di-amd64-cloudinit.txt, its checksum file and the image size were fetched on 21 November 2026, and a failed URL program was run with an image-garden.mk built from the tree and CURL=false ("run"). Portage's behaviour and what the image ships are "derived".
| System | Arch | Boot | Release | URL program reads | Cached as | Checksum |
|---|---|---|---|---|---|---|
gentoo-cloud.x86_64 | x86_64 | efi | none | https://distfiles.gentoo.org/releases/amd64/autobuilds/latest-di-amd64-cloudinit.txt, line 6 | gentoo-cloud-STAMP.x86_64.qcow2 | @URL@.sha256 |
gentoo-cloud.aarch64 | aarch64 | efi | none | https://distfiles.gentoo.org/releases/arm64/autobuilds/latest-di-arm64-cloudinit.txt, line 6 | gentoo-cloud-STAMP.aarch64.qcow2 | @URL@.sha256 |
Image URL pattern: https://distfiles.gentoo.org/releases/ARCH/autobuilds/STAMP/di-ARCH-cloudinit-STAMP.qcow2, with ARCH amd64 or arm64 and STAMP like 20261115T170104Z. Source: gentoo.ini:4-22.
In $GARDEN_DL_DIR/gentoo/:
| File | What |
|---|---|
gentoo-cloud.ARCH.url | the URL the program printed; made again when a makefile changes |
gentoo-cloud.ARCH.filename | gentoo-cloud-STAMP.ARCH.qcow2 |
gentoo-cloud-STAMP.ARCH.qcow2 | the image, one per build fetched |
gentoo-cloud-STAMP.ARCH.qcow2.sha256sums | Gentoo's signed checksum file |
gentoo-cloud.ARCH.qcow2 | a link to the current build |
After a failed URL program, delete gentoo-cloud.ARCH.url and gentoo-cloud.ARCH.filename before you try again: make keeps the empty files.
| Item | Value |
|---|---|
| Template | GENTOO_CLOUD_INIT_USER_DATA_TEMPLATE: the base template plus systemctl enable --now sshd.service (050.gentoo.mk:4-8) |
| Users | root/root; gentoo/gentoo, group users, passwordless sudo |
| Host name | gentoo |
| pkgproxy | /etc/hosts line, snap setup script (runcmd), GOPROXY in /etc/environment; no apt step; Portage not set up |
| Item | Value |
|---|---|
| Size | about 1.2 GB for x86_64 (run, 21 November 2026) |
| spread | upstream spread cannot connect; spread-demo skips it (spread-demo/Makefile:7-13) |
| image-garden CI | x86_64: [others] with Alpine and Arch; no aarch64 job (.gitlab-ci.yml:811-817, .gitlab-ci.yml:889-895) |
| Man page | lists no gentoo-cloud (image-garden.1:211-245) |
13 distribution families with 139 systems, plus 19 Ubuntu Core systems, across six architectures. The full table is under this deck.
mk/050-ubuntu-core.mk adds 9 x86_64 systems, 6 aarch64 systems and 4 x86_64 +tpm systems to GARDEN_SYSTEMS, 19 in all (mk/050-ubuntu-core.mk:4-16).x86_64, aarch64, riscv64, s390x, ppc64 and loongarch64 (rulegen.py:23-29); the README lists the same and the families per architecture (README.md:589-606).Row plus column is the system name: ubuntu-cloud-24.04 + x86_64. A cell gives the boot type; a dash means no such system, so no rule.
Arch value, and its URL the architecture's name (amd64 also counts for x86_64, arm64 for aarch64) (rulegen.py:395-416). Ubuntu's POWER sections end in .ppc64el and still pass, as they contain ppc64: see Ubuntu cloud images.Boot must be one the architecture has rules for: efi or bios on x86_64, efi on aarch64, riscv64 and loongarch64; s390x and ppc64 boot platform and need no Boot (rulegen.py:300-333). A section without a valid Boot stops rulegen.py, so every section in the data has rules.GARDEN_SYSTEMS and gets its rules (rulegen.py:453-478). A name with no section has no rule; the message is GNU make's own "No rule to make target" (derived).ubuntu-cloud-24.04@web.x86_64, are rows your project adds: see named instances.Ubuntu covers five architectures and is the only family on ppc64; Fedora covers four. Together they are all 9 riscv64 and all 12 s390x systems.
Arch Linux, Oracle Linux 7 and the end-of-life Ubuntu interim releases are x86_64 only. Nine families have x86_64 and aarch64. opencloudos-cloud-9 is the one loongarch64 system.
archlinux-cloud.x86_64 is Arch Linux's only section (data/archlinux.ini); oracle-cloud-7 has no aarch64 section (data/oracle.ini).opencloudos-cloud-9 has x86_64, aarch64 and loongarch64 sections (data/opencloudos.ini); the README calls it the only loongarch64 system (README.md:605-606).111 systems boot efi, 6 x86_64 systems bios, and the 22 s390x and ppc64 systems platform, with no firmware file.
Boot is one of platform, efi and bios (rulegen.py:17-20), checked against the architecture: s390x and ppc64 accept only platform, the default there when the key is missing; every other architecture needs Boot (rulegen.py:300-333).amazonlinux-cloud-2.x86_64, centos-cloud-9.x86_64, centos-cloud-10.x86_64, oracle-cloud-7.x86_64, oracle-cloud-8.x86_64 and oracle-cloud-9.x86_64 (data/amazonlinux.ini, data/centos.ini, data/oracle.ini).Boot=efi, 6 with Boot=bios, and the 22 s390x and ppc64 sections without Boot.Boot out on x86_64, aarch64, riscv64 or loongarch64, or names one the architecture has no rules for, stops rulegen.py with FILE: error: Image 'SECTION' has no Boot=, use efi or bios for x86_64 or ... has Boot=bios, which aarch64 does not support, use efi (rulegen.py:312-333, rulegen.py:753-757).image-garden make list-systems prints every system, instances included. all builds and fetch downloads every system of the host's architecture.
list-systems prints GARDEN_SYSTEMS one per line, in the order the makefile adds them: Ubuntu Core first (mk/050-ubuntu-core.mk), then the instances of your project's .image-garden.mk, then the INI families in file order (mk/000-garden.mk:69-87, Makefile:48-50).help, which prints the usage and an example with a random system (mk/000-garden.mk:71-83).all:: and fetch get a system only when GARDEN_ARCH equals its architecture (rulegen.py:456-458, rulegen.py:480-484). GARDEN_ARCH defaults to GARDEN_HOST_ARCH, which is uname -m with ppc64le named ppc64, so a POWER host builds the ppc64 systems (mk/000-garden.mk:14-18).all:: and fetch only on x86_64 and aarch64, the architectures it has rules for (mk/050-ubuntu-core.mk:186-197). Named instances join all too (README.md:529-540).Next: system names, Ubuntu and Ubuntu Core, the six architectures, boot types, loongarch64, and, for contributors, adding a row.
The tables are generated from the data/*.ini files of image-garden v0.8.0 ("code"): every section is one system. Ubuntu Core comes from mk/050-ubuntu-core.mk and the README. Each cell gives the boot type: efi (UEFI firmware), bios, or platform (the architecture's own boot, on s390x and ppc64).
A row's system is NAME.ARCH, for example ubuntu-cloud-24.04.x86_64 or fedora-cloud-42.riscv64. image-garden make NAME.ARCH.run builds and boots it; image-garden make list-systems lists every name. See system names.
| System name | x86_64 | aarch64 | riscv64 | s390x | ppc64 | loongarch64 |
|---|---|---|---|---|---|---|
almalinux-cloud-8 | efi | efi | — | — | — | — |
almalinux-cloud-9 | efi | efi | — | — | — | — |
almalinux-cloud-10 | efi | efi | — | — | — | — |
alpine-cloud-3 | efi | efi | — | — | — | — |
amazonlinux-cloud-2 | bios | efi | — | — | — | — |
amazonlinux-cloud-2023 | efi | efi | — | — | — | — |
archlinux-cloud | efi | — | — | — | — | — |
centos-cloud-9 | bios | efi | — | — | — | — |
centos-cloud-10 | bios | efi | — | — | — | — |
debian-cloud-10 | efi | efi | — | — | — | — |
debian-cloud-11 | efi | efi | — | — | — | — |
debian-cloud-12 | efi | efi | — | — | — | — |
debian-cloud-13 | efi | efi | — | — | — | — |
debian-cloud-14 | efi | efi | — | — | — | — |
debian-cloud-sid | efi | efi | — | — | — | — |
fedora-cloud-38 | efi | efi | — | — | — | — |
fedora-cloud-39 | efi | efi | — | — | — | — |
fedora-cloud-40 | efi | efi | — | — | — | — |
fedora-cloud-41 | efi | efi | — | — | — | — |
fedora-cloud-42 | efi | efi | efi | platform | — | — |
fedora-cloud-43 | efi | efi | efi | platform | — | — |
fedora-cloud-44 | efi | efi | efi | platform | — | — |
fedora-cloud-45 | efi | efi | efi | platform | — | — |
gentoo-cloud | efi | efi | — | — | — | — |
opencloudos-cloud-9 | efi | efi | — | — | — | efi |
opensuse-cloud-15.4 | efi | efi | — | — | — | — |
opensuse-cloud-15.5 | efi | efi | — | — | — | — |
opensuse-cloud-15.6 | efi | efi | — | — | — | — |
opensuse-cloud-16.0 | efi | efi | — | — | — | — |
opensuse-cloud-16.1 | efi | efi | — | — | — | — |
opensuse-cloud-tumbleweed | efi | efi | — | — | — | — |
oracle-cloud-7 | bios | — | — | — | — | — |
oracle-cloud-8 | bios | efi | — | — | — | — |
oracle-cloud-9 | bios | efi | — | — | — | — |
oracle-cloud-10 | efi | efi | — | — | — | — |
rocky-cloud-8 | efi | efi | — | — | — | — |
rocky-cloud-9 | efi | efi | — | — | — | — |
rocky-cloud-10 | efi | efi | — | — | — | — |
ubuntu-cloud-14.04 | efi | efi | — | — | platform | — |
ubuntu-cloud-16.04 | efi | efi | — | — | platform | — |
ubuntu-cloud-16.10 | efi | — | — | — | — | — |
ubuntu-cloud-17.04 | efi | — | — | — | — | — |
ubuntu-cloud-17.10 | efi | — | — | — | — | — |
ubuntu-cloud-18.04 | efi | efi | — | platform | platform | — |
ubuntu-cloud-18.10 | efi | — | — | — | — | — |
ubuntu-cloud-19.04 | efi | — | — | — | — | — |
ubuntu-cloud-19.10 | efi | — | — | — | — | — |
ubuntu-cloud-20.04 | efi | efi | — | platform | platform | — |
ubuntu-cloud-20.10 | efi | — | — | — | — | — |
ubuntu-cloud-21.04 | efi | — | — | — | — | — |
ubuntu-cloud-21.10 | efi | — | — | — | — | — |
ubuntu-cloud-22.04 | efi | efi | — | platform | platform | — |
ubuntu-cloud-22.10 | efi | — | — | — | — | — |
ubuntu-cloud-23.04 | efi | — | — | — | — | — |
ubuntu-cloud-23.10 | efi | — | — | — | — | — |
ubuntu-cloud-24.04 | efi | efi | efi | platform | platform | — |
ubuntu-cloud-24.10 | efi | — | — | — | — | — |
ubuntu-cloud-25.04 | efi | efi | efi | platform | platform | — |
ubuntu-cloud-25.10 | efi | efi | efi | platform | platform | — |
ubuntu-cloud-26.04 | efi | efi | efi | platform | platform | — |
ubuntu-cloud-26.10 | efi | efi | efi | platform | platform | — |
| System name | x86_64 | aarch64 |
|---|---|---|
ubuntu-core-16, -18, -20 | efi | — |
ubuntu-core-22, -24, -26 | efi | efi |
ubuntu-core-22+dangerous, -24+dangerous, -26+dangerous | efi | efi |
ubuntu-core-24+tpm, -26+tpm | efi, Secure Boot, TPM | — |
ubuntu-core-24+dangerous+tpm, -26+dangerous+tpm | efi, Secure Boot, TPM | — |
Modifiers go in alphabetical order (+dangerous+tpm). Ubuntu Core has no root password login: use ubuntu/ubuntu. See Ubuntu Core and Secure Boot and TPM.
old-releases.ubuntu.com for apt; 25.04 and 25.10 are not there yet.ubuntu-core-24 and ubuntu-core-24+tpm; image-garden downloads it once.@NAME before the architecture, such as ubuntu-cloud-24.04@webserver.x86_64: see named instances.opencloudos-cloud-9 on x86_64, aarch64 and loongarch64, the only loongarch64 system: image-garden make opencloudos-cloud-9.loongarch64.run.
data/opencloudos.ini: Group=opencloudos, Variant=cloud, and [opencloudos-cloud-9.x86_64], [opencloudos-cloud-9.aarch64] and [opencloudos-cloud-9.loongarch64], each with Release=9 (opencloudos.ini:9-32).The download names build 20260922.0 of 9.6, checked against the .sha256 file next to the image. Everyone gets the same image, until a new image-garden names a newer build.
https://mirrors.opencloudos.tech/opencloudos/9.6/images/qcow2/ARCH/20260922.0/OpenCloudOS-GenericCloud-9.6-20260922.0.ARCH.qcow2, with SHA256SUMS=@URL@.sha256 (opencloudos.ini:13-32). @URL@ is the URL from the .url file (rulegen.py:51-58)..sha256 file holds one line, HASH OpenCloudOS-GenericCloud-9.6-20260922.0.x86_64.qcow2 (run with curl on 21 November 2026); the x86_64 image was 839712768 bytes.9, the Release=; the point release and the build are only in the URL. On 21 November 2026 the mirror answered through a content delivery network (run); where it is served from is not in the tree.UEFI on all three. x86_64 on q35 and aarch64 on virt run with KVM on a matching host; loongarch64, on virt, is emulated on a PC. On any host, only its own architecture gets KVM.
Boot=efi in all three sections (opencloudos.ini:13-32); x86_64 may boot efi or bios, aarch64 and loongarch64 only efi (rulegen.py:300-309).q35 with -cpu max on x86_64 (010-qemu-x86_64.mk:5-6), virt,gic-version=max on aarch64 (010-qemu-aarch64.mk:4-5), virt with -cpu max on loongarch64 (010-qemu-loongarch64.mk:4-5). Each asks for kvm:tcg when QEMU lists KVM, so on a LoongArch host the loongarch64 system would use KVM too (010-qemu-loongarch64.mk:13-14); the host's own architecture also gets 4 vCPUs (010-qemu.mk:5-6).x86_64: [el 2/2] (.gitlab-ci.yml:833-839) and aarch64: [el], on Raspberry Pi 5s, allowed to fail (.gitlab-ci.yml:897-905, .gitlab-ci.yml:649-652); loongarch64: [el] with Ubuntu's qemu-system-misc and qemu-efi-loongarch64 (.gitlab-ci.yml:1004-1015) extends .systems-emulated: GARDEN_TEST_BOOT_ONLY: "1", allow_failure: true, run on version tags and by hand elsewhere (.gitlab-ci.yml:663-690).The common template: root/root and opencloudos/opencloudos with sudo, host name opencloudos-9. pkgproxy adds its hosts line, the snap setup and GOPROXY; the package manager is not set up.
mk/ file names OpenCloudOS: no OPENCLOUDOS_9_ or OPENCLOUDOS_ template is defined, so the picker falls back to the common template (010-qemu.mk:285-298); the user-data passes the group opencloudos and the release 9 (rulegen.py:467).root/root, and opencloudos/opencloudos in users with passwordless sudo (010-qemu.mk:200-211); spread-demo logs in with opencloudos/opencloudos (spread-demo/spread.yaml:258-261).local-hostname: opencloudos-9, the group and release joined by a dash (010-qemu.mk:94-104); the meta-data's instance-id is iid-opencloudos-9./etc/hosts line, the snap script from runcmd, no apt script, and GOPROXY in /etc/environment (010-qemu.mk:127-180). pkgproxy serves apt, the snap store and Go modules (proxy/README.md:40-48). That OpenCloudOS 9 installs packages with dnf from its own repositories is the distribution's behaviour (derived).Packages are as old as the pinned build until a test updates them. The first, uncached download dominates; pkgproxy keeps the image by its checksum. Emulated loongarch64 is slow.
Next: loongarch64, the support matrix, the users, pkgproxy family by family, the six architectures, and Enterprise Linux.
Read in data/opencloudos.ini, rulegen.py, mk/010-qemu.mk and the per-architecture make files, the image-garden script, the README, NEWS and .gitlab-ci.yml of image-garden at the commit in garden.commit ("code"). The checksum file and the image size were fetched from the mirror on 21 November 2026 ("run"). Where the mirror is served from, and how dnf behaves in the guest, are "derived".
| System | Arch | Boot | Release | Image | Checksum |
|---|---|---|---|---|---|
opencloudos-cloud-9.x86_64 | x86_64 | efi | 9 | OpenCloudOS-GenericCloud-9.6-20260922.0.x86_64.qcow2 | @URL@.sha256 |
opencloudos-cloud-9.aarch64 | aarch64 | efi | 9 | OpenCloudOS-GenericCloud-9.6-20260922.0.aarch64.qcow2 | @URL@.sha256 |
opencloudos-cloud-9.loongarch64 | loongarch64 | efi | 9 | OpenCloudOS-GenericCloud-9.6-20260922.0.loongarch64.qcow2 | @URL@.sha256 |
Image URL pattern: https://mirrors.opencloudos.tech/opencloudos/9.6/images/qcow2/ARCH/20260922.0/OpenCloudOS-GenericCloud-9.6-20260922.0.ARCH.qcow2; the checksum is that URL plus .sha256, a one-line HASH NAME file. Source: opencloudos.ini:4-32.
| Arch | Machine | Usual host | CI job |
|---|---|---|---|
| x86_64 | q35, -cpu max | a PC, with KVM | x86_64: [el 2/2] |
| aarch64 | virt,gic-version=max, -cpu max | a 64-bit Arm machine, with KVM | aarch64: [el] (may fail) |
| loongarch64 | virt, -cpu max | a PC, emulated | loongarch64: [el] (boot only, may fail) |
The loongarch64 machine's options, firmware search list and per-install support are in loongarch64 and OpenCloudOS.
| Item | Value |
|---|---|
| Template | the common template (no OpenCloudOS quirk) |
| Users | root/root; opencloudos/opencloudos, group users, passwordless sudo |
| Host name | opencloudos-9 |
| pkgproxy | /etc/hosts line, snap setup script (runcmd), GOPROXY in /etc/environment; no apt step; the package manager not set up |
| Updates | none asked for at first boot |
Sources: 010-qemu.mk:94-104, 010-qemu.mk:127-180, 010-qemu.mk:187-247.
| Item | Value |
|---|---|
| Size | about 840 MB for x86_64 (run, 21 November 2026) |
| First download in CI | 6.8 of 8.4 minutes, uncached (.gitlab-ci.yml:1004-1005) |
| spread | opencloudos-cloud-9 with opencloudos/opencloudos in spread-demo |
| A newer build | comes with an edit to data/opencloudos.ini, in a new image-garden |
Twelve systems: Leap 15.4, 15.5, 15.6, 16.0, 16.1 and Tumbleweed, each on x86_64 and aarch64, all booting with EFI.
data/opensuse.ini starts with [META]: Group=opensuse, Variant=cloud (opensuse.ini:4-6), then twelve sections, opensuse-cloud-15.4 to opensuse-cloud-16.1 and opensuse-cloud-tumbleweed, each on x86_64 and aarch64 with Boot=efi (opensuse.ini:8-90).Leap 15 from repositories/Cloud:/Images:/Leap_15.x, Leap 16 from distribution/leap/16.x/appliances, Tumbleweed from Virtualization:/Appliances:/Images:/openSUSE-Tumbleweed; each checked against IMAGE.sha256.
https://download.opensuse.org/repositories/Cloud:/Images:/Leap_15.x/images/openSUSE-Leap-15.x.ARCH-NoCloud.qcow2 (opensuse.ini:8-48).https://download.opensuse.org/distribution/leap/16.x/appliances/Leap-16.x-Minimal-VM.ARCH-Cloud.qcow2 (opensuse.ini:50-76). NEWS records two fixes to the 16.0 URLs, the later one moving them from stale build files to the final release images (NEWS:229-231).https://download.opensuse.org/repositories/Virtualization:/Appliances:/Images:/openSUSE-Tumbleweed/openSUSE_Tumbleweed/openSUSE-Tumbleweed-Minimal-VM.x86_64-Cloud.qcow2, and openSUSE_Tumbleweed_ARM/…aarch64-Cloud.qcow2 for aarch64 (opensuse.ini:78-90).SHA256SUMS= is the image URL plus .sha256. A section with SHA256SUMS= gets download-with-sha256sums (rulegen.py:510-514), which saves the file as FILE.sha256sums, finds the hash by the file's name, and checks with sha256sum --check (image-garden:460-559, image-garden:75-92).repositories/ trees, and what the NoCloud and Cloud flavours hold, is openSUSE's practice (derived).Users root/root and opensuse/opensuse, host name opensuse-16-0. With pkgproxy: /etc/hosts, snap setup and GOPROXY; nothing for zypper.
root/root, and opensuse/opensuse in group users with sudo: ["ALL=(ALL) NOPASSWD:ALL"] and bash (010-qemu.mk:200-211, rulegen.py:467).16.0 gives opensuse-16-0 and Tumbleweed opensuse-tumbleweed (010-qemu.mk:94-104).PKGPROXY_BOOTCMD_SETUP names apt only for debian and ubuntu; PKGPROXY_RUNCMD_SETUP names snap for every group but alpine (010-qemu.mk:127-130). bootcmd still adds /etc/hosts and probes pkgproxy (010-qemu.mk:156-162); GOPROXY goes to /etc/environment (010-qemu.mk:170-180).if [ -d /etc/apt ] (010-qemu.mk:244).mk/ gives openSUSE a template; the only openSUSE entries in mk/ are the aarch64 firmware list of the next scene and a comment on firmware paths (010-qemu-x86_64.mk:260).opensuse-cloud-15.4 and 15.5 on aarch64 are in GARDEN_AARCH64_FEDORA_EDK2_SYSTEMS and boot with Fedora's EDK2.
GARDEN_AARCH64_FEDORA_EDK2_SYSTEMS lists ten systems, among them opensuse-cloud-15.4 and opensuse-cloud-15.5; the comment above it gives the reason: boot loaders that "predate what newer EDK2 enforces", which stop with "Synchronous Exception" under the EDK2 Debian and Ubuntu build (010-qemu-aarch64.mk:114-145).qemu-aarch64 component; elsewhere the code and vars files are downloaded with download-with-sha256sum from the project's generic package edk2-aarch64-fedora (010-qemu-aarch64.mk:147-160). NEWS: "Older aarch64 systems boot again", openSUSE Leap 15.4 and 15.5 among them (NEWS:145-152).?=, so a project or the command line can change the list.opensuse-cloud-15.4, 15.5, 15.6 and tumbleweed, and may fail without failing the pipeline (.gitlab-ci.yml:881-887, .gitlab-ci.yml:636-652); the x86_64 job tests all six (.gitlab-ci.yml:803-809).Tumbleweed's image name never changes: remove it and its .sha256sums file from the cache to update. zypper, not apt; SELinux on Leap 16, AppArmor on Leap 15.
openSUSE-Tumbleweed-Minimal-VM.x86_64-Cloud.qcow2 (opensuse.ini:78-90), and so do the Leap 16 appliances. The helper fetches the checksum file and the image only when they are missing from the cache (image-garden:475-559); distclean removes the image but not FILE.sha256sums (rulegen.py:486-492). So the first download stays until both are removed from the cache's opensuse/ directory (derived from the code; the Debian deck walks through it).getenforce in the guest.data/opensuse.ini and in its CI (.gitlab-ci.yml:803-809).Next: UEFI firmware, the users, pkgproxy in the user-data, downloads, Debian and the support matrix.
Read in data/opensuse.ini, rulegen.py, mk/010-qemu.mk, mk/010-qemu-aarch64.mk, the image-garden script, proxy/README.md, README.md, NEWS and .gitlab-ci.yml of image-garden at the commit in garden.commit ("code"). openSUSE's release model, its package manager and its security modules are general knowledge ("derived"), as is the cache behaviour of images whose name does not change, worked out from the download helper. Nothing was run for this page.
The system name is opensuse-cloud-RELEASE.ARCH. Every system boots with efi. The aarch64 firmware column says which EDK2 the aarch64 system boots with (UEFI firmware per system).
| System | Release | Architectures | Boot | Source | aarch64 firmware | Host name |
|---|---|---|---|---|---|---|
opensuse-cloud-15.4 | Leap 15.4 | x86_64, aarch64 | efi | Cloud:Images:Leap_15.4, NoCloud | Fedora's EDK2 | opensuse-15-4 |
opensuse-cloud-15.5 | Leap 15.5 | x86_64, aarch64 | efi | Cloud:Images:Leap_15.5, NoCloud | Fedora's EDK2 | opensuse-15-5 |
opensuse-cloud-15.6 | Leap 15.6 | x86_64, aarch64 | efi | Cloud:Images:Leap_15.6, NoCloud | usual | opensuse-15-6 |
opensuse-cloud-16.0 | Leap 16.0 | x86_64, aarch64 | efi | distribution/leap/16.0/appliances, Minimal-VM Cloud | usual | opensuse-16-0 |
opensuse-cloud-16.1 | Leap 16.1 | x86_64, aarch64 | efi | distribution/leap/16.1/appliances, Minimal-VM Cloud | usual | opensuse-16-1 |
opensuse-cloud-tumbleweed | Tumbleweed | x86_64, aarch64 | efi | Virtualization:Appliances:Images:openSUSE-Tumbleweed, Minimal-VM Cloud | usual | opensuse-tumbleweed |
ARCH is x86_64 or aarch64, spelled the same way in the URLs. Every checksum file is the image URL with .sha256 appended: openSUSE's file with the image's hash, saved in the cache as FILE.sha256sums.
Leap 15.x: https://download.opensuse.org/repositories/Cloud:/Images:/Leap_15.x/images/openSUSE-Leap-15.x.ARCH-NoCloud.qcow2
Leap 16.x: https://download.opensuse.org/distribution/leap/16.x/appliances/Leap-16.x-Minimal-VM.ARCH-Cloud.qcow2
Tumbleweed: https://download.opensuse.org/repositories/Virtualization:/Appliances:/Images:/openSUSE-Tumbleweed/REPO/openSUSE-Tumbleweed-Minimal-VM.ARCH-Cloud.qcow2
REPO is openSUSE_Tumbleweed for x86_64, openSUSE_Tumbleweed_ARM for aarch64
SHA256SUMS: the image URL + .sha256
None of these names carries a build date, so a cached image stays until it and its .sha256sums file are removed (The same name every day shows how).
| What | On openSUSE | Source |
|---|---|---|
| Users | root/root; opensuse/opensuse in group users, passwordless sudo, bash | 010-qemu.mk:200-211 |
| Host name | opensuse-RELEASE with dots as dashes, such as opensuse-16-0 | 010-qemu.mk:94-104 |
| SSH | password logins, root may log in | 010-qemu.mk:212-243 |
| apt sources | nothing: there is no /etc/apt | 010-qemu.mk:244 |
| pkgproxy, bootcmd | /etc/hosts entry and reachability probe; no setup script | 010-qemu.mk:127-162 |
| pkgproxy, runcmd | /etc/hosts entry again, pkgproxy's snap setup script | 010-qemu.mk:164-168 |
| pkgproxy, files | GOPROXY appended to /etc/environment | 010-qemu.mk:170-180 |
| zypper | nothing: packages come from openSUSE's mirrors | 010-qemu.mk:127-130 |
| Distribution quirks | none in the user-data; Fedora's EDK2 for 15.4 and 15.5 on aarch64 | 010-qemu-aarch64.mk:134-145 |
$ image-garden make opensuse-cloud-16.0.x86_64.run $ ./opensuse-cloud-16.0.x86_64.run --query
In spread.yaml the systems are opensuse-cloud-15.4 to opensuse-cloud-tumbleweed, with username: opensuse and password: opensuse, as in image-garden's spread demo (spread-demo/spread.yaml:262-280).
ubuntu-core-24+tpm, ubuntu-core-24+dangerous+tpm, ubuntu-core-26+tpm and ubuntu-core-26+dangerous+tpm boot on x86_64 with Secure Boot and an emulated TPM 2.0.
UBUNTU_CORE_TPM_RELEASES = 24+tpm 24+dangerous+tpm 26+tpm 26+dangerous+tpm, added to GARDEN_SYSTEMS for x86_64 only (mk/050-ubuntu-core.mk:9-16). make stops +tpm+dangerous (wrong order) and a +tpm goal that is not x86_64 (mk/050-ubuntu-core.mk:18-21).+tpm systems, for x86\_64 only, boot with Secure Boot and a TPM 2.0 emulated by swtpm" (README.md:702-718); the release notes (NEWS:45-48).-machine q35,smm=on, the OVMF Secure Boot pair with secure pflash, and -device tpm-crb backed by swtpm over a UNIX socket.
QEMU_SYSTEM_X86_64_MACHINE = q35,smm=on for the +tpm .run and .qcow2; their firmware copies come from efi-secboot-code.x86_64.img and efi-secboot-vars.x86_64.img (mk/050-ubuntu-core.mk:55-61), the pair OVMF_CODE_4M.secboot.fd and OVMF_VARS_4M.ms.fd "with the Microsoft keys enrolled, so that the signed shim boots" (mk/010-qemu-x86_64.mk:282-289).QEMU_SECURE_PFLASH_OPTION = -global driver=cfi.pflash01,property=secure,value=on and QEMU_TPM_OPTION_FOR = -chardev socket,id=chrtpm,path=SOCK -tpmdev emulator,id=tpm0,chardev=chrtpm -device tpm-crb,tpmdev=tpm0 (mk/010-qemu-x86_64.mk:132-135); the launcher macro's comment (mk/010-qemu-x86_64.mk:53-58)..run script the TPM option is QEMU_TPM_OPTION, which can be overridden like the others (mk/010-qemu-x86_64.mk:71, :80).QEMU_TPM_OPTION: by default a tpm-crb device connected to the swtpm the .run script starts (README.md:941-942, image-garden.1:665-669).Making ubuntu-core-24+tpm.x86_64.qcow2 creates ubuntu-core-24+tpm.x86_64.tpm/ (mode 700), runs swtpm on it and boots install mode, which encrypts ubuntu-data and ubuntu-save and seals the keys.
.qcow2 rule: checks swtpm, rm -rf and mkdir -m 700 the state directory, creates the overlay, makes a run directory under $XDG_RUNTIME_DIR/image-garden/tpm.XXXXXXXX (or $TMPDIR), runs swtpm socket --tpm2 --tpmstate dir=… --ctrl type=unixio,path=…/swtpm.sock --pid file=… --terminate --daemon, then QEMU with the secure flash, the TPM and the seed on a virtio SCSI CD-ROM (mk/050-ubuntu-core.mk:70-98)..DELETE_ON_ERROR removes the failed target (mk/000-garden.mk:7).+ turned into -, as a host name label allows no +: ubuntu-core-24-tpm, ubuntu-core-24-dangerous-tpm, in user-data and meta-data alike (mk/050-ubuntu-core.mk:141, mk/010-qemu.mk:94-104).SecureBoot = 1 and CRYPT-* devices under /run/mnt/data and /run/mnt/ubuntu-save (spread-demo/tests/smoke/tpm/task.yaml:15-51).X.qcow2, X.efi-vars.qcow2 and X.tpm/ go together. The launcher refuses to run from another directory and stops when X.tpm/ is missing.
pwd -P with its own directory and checks the state directory (mk/010-qemu-x86_64.mk:159-172)./home/you/project is an example.SYSTEM.x86_64.tpm/ directory "belongs with the .qcow2 and .efi-vars.qcow2 files: copy or remove them together" (README.md:711-716, README.md:836-837). make clean removes the .tpm directories (mk/050-ubuntu-core.mk:314-318).The launcher starts swtpm in $XDG_RUNTIME_DIR/image-garden/tpm.XXXXXXXX, or port.PORT.tpm under allocate; with -snapshot swtpm gets a copy of the state.
EMIT_SWTPM_START: run directory from GARDEN_TPM_RUN_DIR, or mktemp -d under $XDG_RUNTIME_DIR/image-garden (in the snap's runtime directory when run from outside the snap), else under $TMPDIR; with -snapshot among the arguments it copies the state with cp -a; swtpm runs with --terminate --daemon; a watcher tail --pid=… -f /dev/null; rm -rf … removes the directory (mk/010-qemu-x86_64.mk:137-205). If QEMU fails, the launcher kills swtpm (mk/010-qemu-x86_64.mk:207-216).GARDEN_TPM_RUN_DIR=$XDG_RUNTIME_DIR/image-garden/port.PORT.tpm (image-garden:825-831, image-garden:1108-1112); discard_tpm_run_dir waits for swtpm, kills it if needed and removes the directory (image-garden:833-859)..run script of any system passes -snapshot on when you give it (see the .run script).Outside the snap: the swtpm and ovmf packages. The container has both. The snap: snap install image-garden+swtpm.
swtpm and the Secure Boot firmware of the ovmf package" (README.md:122-126). The container installs ovmf and swtpm (Dockerfile:78-91).SWTPM_MISSING_MESSAGE = swtpm, the TPM emulator, is required: install the swtpm package, printed by the .qcow2 rule and by the launcher (mk/010-qemu-x86_64.mk:115-120, mk/050-ubuntu-core.mk:79).check-swtpm-component prints "install the swtpm component to use systems with a TPM: snap install image-garden+swtpm" (mk/010-qemu-x86_64.mk:121-131); the link to the download depends on it first, so nothing is downloaded (mk/050-ubuntu-core.mk:74-76, mk/050-ubuntu-core.mk:279-289).image-garden.swtpm app lets a launcher run from a shell outside the snap (README.md:322-334, snap/snapcraft.yaml:109-139). Missing the Secure Boot firmware gives the message in the Secure Boot pair.Next: how a TPM system is launched, +dangerous systems, encryption on the snapd map, the snap's swtpm component, Ubuntu Core and the firmware.
Read in mk/050-ubuntu-core.mk, mk/010-qemu-x86_64.mk, image-garden, README.md, snap/snapcraft.yaml, the Dockerfile and spread-demo/tests/smoke/tpm/task.yaml of image-garden at the tag in garden.commit ("code"). What snapd does in install mode is from the README and the test; nothing was run for this page.
| System | Host name in the guest | Downloaded image | cdimage directory |
|---|---|---|---|
ubuntu-core-24+tpm.x86_64 | ubuntu-core-24-tpm | ubuntu-core-24-amd64.img.xz | ubuntu-core/24/stable |
ubuntu-core-24+dangerous+tpm.x86_64 | ubuntu-core-24-dangerous-tpm | ubuntu-core-24+dangerous-amd64.img.xz | ubuntu-core/24/dangerous-stable |
ubuntu-core-26+tpm.x86_64 | ubuntu-core-26-tpm | ubuntu-core-26-amd64.img.xz | ubuntu-core/26/stable |
ubuntu-core-26+dangerous+tpm.x86_64 | ubuntu-core-26-dangerous-tpm | ubuntu-core-26+dangerous-amd64.img.xz | ubuntu-core/26/dangerous-stable |
In spread they are ubuntu-core-24-plus-tpm and so on (see system names).
| File | Made by | Holds |
|---|---|---|
X.qcow2 | the provisioning boot | the encrypted disk, an overlay on the shared download |
X.efi-code.qcow2 | $(QEMU_IMG) convert of efi-secboot-code.x86_64.img | OVMF Secure Boot code |
X.efi-vars.qcow2 | $(QEMU_IMG) convert of efi-secboot-vars.x86_64.img | the UEFI variables, Microsoft keys enrolled |
X.tpm/ | mkdir -m 700 in the .qcow2 rule | swtpm's TPM state, to which the keys are sealed |
X.qcow2.log | tee | the serial console of the provisioning boot, with the journal |
X.run | the launcher rule | starts swtpm, then QEMU |
| Message | When |
|---|---|
swtpm, the TPM emulator, is required: install the swtpm package | no swtpm on PATH, at make or launch |
install the swtpm component to use systems with a TPM: snap install image-garden+swtpm | in the snap, before the download |
please install x86_64 edk2 firmware with Secure Boot and Microsoft keys (the ovmf package) - not in … | no Secure Boot pair found |
X.qcow2: QEMU was stopped by a signal before the install finished | the provisioning QEMU was killed |
$0: run this launcher from its own directory, DIR: its disk is sealed to the TPM state there | launcher started from elsewhere |
$0: the TPM state, DIR/X.tpm, is missing: make the .qcow2 image again | the state directory is gone |
X: system modifiers go in alphabetical order: use …+dangerous+tpm… | +tpm+dangerous in a goal |
X: ubuntu-core with +tpm is only available for x86_64 | a +tpm goal on aarch64 |
| Install | swtpm | Secure Boot OVMF |
|---|---|---|
| Distribution or source | the swtpm package | the ovmf package |
| Container | included | included |
| Snap | snap install image-garden+swtpm | in the qemu-x86-64 component |
56 systems: 23 releases from 14.04 to 26.10, from cloud-images.ubuntu.com.
data/ubuntu.ini starts with [META]: Group=ubuntu, Variant=cloud (ubuntu.ini:4-6), then one section per system, 56 in all, grouped under codename comments from trusty to stonking.LTS releases are on x86_64, aarch64 and ppc64, s390x from 18.04, riscv64 from 24.04. 25.04 to 26.10 have all five; interim releases from 16.10 to 24.10 only x86_64.
.ppc64el" (README.md:692-697).Live releases point at …/CODENAME/current/; end-of-life interim releases at …/releases/CODENAME/release…/. Thirteen of them, 16.10 to 24.10, are x86_64 only.
https://cloud-images.ubuntu.com/CODENAME/current/, as ubuntu.ini:237-242. End-of-life interim releases use https://cloud-images.ubuntu.com/releases/CODENAME/release-DATE/ or …/release/, as 16.10 and 17.10 (ubuntu.ini:52-77); 25.04 already uses releases/plucky/release/.current/ and moves end-of-life archives to old-releases.ubuntu.com is Ubuntu's practice (derived); the makefile's comment gives the rule it uses: a codename missing from archive.ubuntu.com/ubuntu/dists/ needs old-releases (mk/050-ubuntu.mk:4-8).For 16.10 to 24.10 the user-data sets apt's primary and security archives to http://old-releases.ubuntu.com/ubuntu. 25.04 and 25.10 are not on the list yet.
UBUNTU_OLD_RELEASES_VERSIONS = 16.10 17.04 17.10 18.10 19.04 19.10 20.10 21.04 21.10 22.10 23.04 23.10 24.10; for group ubuntu and a release in that list, UBUNTU_OLD_RELEASES_APT_CONFIG gives an apt: block with preserve_sources_list: false and primary and security set to http://old-releases.ubuntu.com/ubuntu (mk/050-ubuntu.mk:12-24); EXTRA_CLOUD_INIT_APT_CONFIG calls it (mk/050-ubuntu.mk:26-28).$(call EXTRA_CLOUD_INIT_APT_CONFIG,$1,$3) near its top, with the group and the release (mk/010-qemu.mk:198); rulegen passes the release as the third argument (rulegen.py:467).https to http in /etc/apt/*.list, a pkgproxy's apt setup still applies to these sources (see per-distro quirks).Ubuntu's POWER systems are named ubuntu-cloud-R.ppc64el and run on qemu-system-ppc64, with no firmware file. image-garden counts a ppc64le host as ppc64; $(uname -m) in your own scripts matches nothing.
ubuntu-cloud-R.ppc64el, with Arch=ppc64 and no Boot (ubuntu.ini:24-28, ubuntu.ini:264-268). rulegen requires only that the name contain the Arch value, which ppc64el does (rulegen.py:395-405).Boot means platform, the only boot type ppc64 accepts (rulegen.py:300-333); ppc64 systems get the ppc64 rules, with the pseries machine (rulegen.py:820-821, mk/010-qemu-ppc64.mk:4-5).uname -m prints ppc64le on a little-endian POWER host (derived). The README's spread example appends $(uname -m) to the system name (README.md:740-745), which gives no Ubuntu POWER system there.GARDEN_HOST_ARCH is uname -m with ppc64le named ppc64, and GARDEN_ARCH defaults to it (mk/000-garden.mk:14-17). The rules compare GARDEN_ARCH with ppc64 (rulegen.py:456-458), so image-garden make all on a POWER host builds the ppc64el systems, and QEMU_SMP_PPC64 is the variable raised to 4 (mk/010-qemu.mk:5-6). NEWS: "On a ppc64le host the ppc64 systems are native" (NEWS:19-20).Arch=, not from the .ppc64el suffix, so their .run scripts have the ppc64 command and they join all on a POWER host (mk/020-instances.mk:53-65).Next: system names, Ubuntu Core, the support matrix, the six architectures, per-distro quirks and ppc64.
The table is generated from data/ubuntu.ini and mk/050-ubuntu.mk of image-garden at the tag in garden.commit ("code"): the codenames are the file's comments, the architecture suffixes its section names. Which releases are LTS and which have reached their end of life is Ubuntu's release cycle ("derived"), as the makefile's comments record it. Nothing was run for this page.
The system name is ubuntu-cloud-RELEASE.SUFFIX, such as ubuntu-cloud-24.04.x86_64 or ubuntu-cloud-24.04.ppc64el. The apt column is where the first boot points apt; image-garden changes it only for the releases marked old-releases.
| Release | Codename | Kind | Suffixes | apt archive |
|---|---|---|---|---|
| 14.04 | trusty | LTS | x86_64, aarch64, ppc64el | archive.ubuntu.com |
| 16.04 | xenial | LTS | x86_64, aarch64, ppc64el | archive.ubuntu.com |
| 16.10 | yakkety | interim, end of life | x86_64 | old-releases.ubuntu.com |
| 17.04 | zesty | interim, end of life | x86_64 | old-releases.ubuntu.com |
| 17.10 | artful | interim, end of life | x86_64 | old-releases.ubuntu.com |
| 18.04 | bionic | LTS | x86_64, aarch64, s390x, ppc64el | archive.ubuntu.com |
| 18.10 | cosmic | interim, end of life | x86_64 | old-releases.ubuntu.com |
| 19.04 | disco | interim, end of life | x86_64 | old-releases.ubuntu.com |
| 19.10 | eoan | interim, end of life | x86_64 | old-releases.ubuntu.com |
| 20.04 | focal | LTS | x86_64, aarch64, s390x, ppc64el | archive.ubuntu.com |
| 20.10 | groovy | interim, end of life | x86_64 | old-releases.ubuntu.com |
| 21.04 | hirsute | interim, end of life | x86_64 | old-releases.ubuntu.com |
| 21.10 | impish | interim, end of life | x86_64 | old-releases.ubuntu.com |
| 22.04 | jammy | LTS | x86_64, aarch64, s390x, ppc64el | archive.ubuntu.com |
| 22.10 | kinetic | interim, end of life | x86_64 | old-releases.ubuntu.com |
| 23.04 | lunar | interim, end of life | x86_64 | old-releases.ubuntu.com |
| 23.10 | mantic | interim, end of life | x86_64 | old-releases.ubuntu.com |
| 24.04 | noble | LTS | x86_64, aarch64, riscv64, s390x, ppc64el | archive.ubuntu.com |
| 24.10 | oracular | interim, end of life | x86_64 | old-releases.ubuntu.com |
| 25.04 | plucky | interim, end of life | x86_64, aarch64, riscv64, s390x, ppc64el | archive.ubuntu.com |
| 25.10 | questing | interim, end of life | x86_64, aarch64, riscv64, s390x, ppc64el | archive.ubuntu.com |
| 26.04 | resolute | LTS | x86_64, aarch64, riscv64, s390x, ppc64el | archive.ubuntu.com |
| 26.10 | stonking | interim | x86_64, aarch64, riscv64, s390x, ppc64el | archive.ubuntu.com |
https://cloud-images.ubuntu.com/CODENAME/current/, end-of-life interim releases from …/releases/CODENAME/release…/, each with its SHA256SUMS (data/ubuntu.ini).efi on x86_64, aarch64 and riscv64; no Boot key, so platform, on s390x and ppc64.uname -m prints ppc64le, which image-garden counts as ppc64, so image-garden make all there builds the .ppc64el systems with 4 vCPUs (mk/000-garden.mk:14-17). Named instances of them work too.UBUNTU_OLD_RELEASES_VERSIONS lists the releases whose user-data points apt at http://old-releases.ubuntu.com/ubuntu (mk/050-ubuntu.mk:12-28).root/root and ubuntu/ubuntu, as for every cloud system (insecure on purpose).Ubuntu Core 16 to 26 on x86_64, 22 to 26 on aarch64, with +dangerous and +tpm variants. The example is ubuntu-core-24.x86_64.
UBUNTU_CORE_RELEASES = 16 18 20 22 22+dangerous 24 24+dangerous 26 26+dangerous; all are x86_64 systems, and all but 16, 18 and 20 are aarch64 systems too (050-ubuntu-core.mk:4-7).24+tpm 24+dangerous+tpm 26+tpm 26+dangerous+tpm, x86_64 only (050-ubuntu-core.mk:15-16).Images come from cdimage.ubuntu.com/ubuntu-core/R/stable or …/dangerous-stable. The .img.xz is converted to qcow2 once, under a lock, and shared by the systems built on it.
ubuntu-core-R-ARCH.img.xz and its SHA256SUMS with image-garden download-with-sha256sums from https://cdimage.ubuntu.com/ubuntu-core/R/stable/current/ or, for +dangerous, …/R/dangerous-stable/current/ (050-ubuntu-core.mk:216-251).%.qcow2: %.img.xz unpacks with unxz and converts with qemu-img convert inside GARDEN_LOCKED_RECIPE, which takes flock on TARGET.lock; a second make that waits finds the target newer than its source and keeps it (010-qemu.mk:304-347).ubuntu-core-24.x86_64.qcow2 and ubuntu-core-24+tpm.x86_64.qcow2 in the cache are both links to ubuntu-core-24-amd64.qcow2; the +dangerous+tpm systems link to the +dangerous file (050-ubuntu-core.mk:273-289).BASE_UBUNTU_CORE_CLOUD_INIT_USER_DATA_TEMPLATE: journal to the serial console, refresh.hold, useradd --extrausers ubuntu, console-conf skipped, snap wait system seed.loaded, power off.
BASE_UBUNTU_CORE_CLOUD_INIT_USER_DATA_TEMPLATE (050-ubuntu-core.mk:131-177), set as UBUNTU_CORE_CLOUD_INIT_USER_DATA_TEMPLATE (050-ubuntu-core.mk:179): - datasource_list: [NoCloud], manage_etc_hosts, ssh_pwauth: true, power_state poweroff; - bootcmd writes /run/systemd/journald.conf.d/90-image-garden-console.conf with ForwardToConsole=yes and the serial TTYPath, then restarts journald (lines 144-159); - runcmd: snap set system refresh.hold= tomorrow (162), ip link set dev eth0 down (164), useradd … --extrausers ubuntu and chpasswd (166-167), console-conf marked complete (168), snap wait system seed.loaded (170), snap abort 3 || true (172), snap remove --purge console-conf || true (174), ip link set dev eth0 up (176).CLOUD_INIT_HOSTNAME of ubuntu-core and the release, with dots and pluses turned to dashes: ubuntu-core-24, or ubuntu-core-24-tpm for ubuntu-core-24+tpm; the meta-data local-hostname is the same name (050-ubuntu-core.mk:141, 010-qemu.mk:94-104, 050-ubuntu-core.mk:111).set -o pipefail, so a QEMU that fails to start or exits with an error fails the build instead of leaving an image that looks ready (050-ubuntu-core.mk:37-53).UBUNTU_CORE and the release, such as 24+dangerous (050-ubuntu-core.mk:116).Ubuntu Core has no root password login: use ubuntu/ubuntu and sudo. SYSTEM.run --query reports only that user.
only:ubuntu account list (050-ubuntu-core.mk:22-26), for which --query prints only system.users.0.username=ubuntu and system.users.0.password=ubuntu; cloud images print root and the distribution's user (010-qemu.mk:80-87).--query reports and use sudo when it is not root (snapcraft-gitlab-ci bin/snapcraft-vm, see the craft components).x86_64: 16–26, +dangerous for 22–26, +tpm for 24 and 26. aarch64: 22–26 and +dangerous. Modifiers go in alphabetical order: +dangerous+tpm.
+tpm+dangerous ("system modifiers go in alphabetical order: use …+dangerous+tpm…") and an Ubuntu Core +tpm goal that is not x86_64 ("ubuntu-core with +tpm is only available for x86_64") (050-ubuntu-core.mk:18-21).image-garden make all and fetch include Ubuntu Core only on x86_64 and aarch64 hosts: 22 to 26 and their modifiers on both, 16 to 20 and the +tpm systems on x86_64 only (050-ubuntu-core.mk:186-197). On other hosts the Ubuntu Core systems can still be named and emulated.define-instance works on the systems of data/*.ini, and with an Ubuntu Core base make has no rule for the instance (README.md:976-979).virtio-scsi-pci and scsi-hd (050-ubuntu-core.mk:181-184); every Ubuntu Core seed is attached as a SCSI CD-ROM (050-ubuntu-core.mk:38-44).Next: +dangerous systems, Secure Boot and TPM, and on the snapd map the model and how Ubuntu Core boots.