What a native install needs from the host

QEMU, OVMF, swtpm, curl for users

A package or source install brings only the script and image-garden.mk; the host supplies make, curl, xorriso, qemu-img, a qemu-system emulator per architecture, EDK2 firmware, and swtpm with the Secure Boot OVMF for the +tpm systems, each looked for only when the step that needs it runs.

On the map: native

▶ Watch this deck — 6 scenes, ~4 min

Worth seeing first

01 Everything but the script comes from your host

WHAT THE HOST SUPPLIES a native install brings image-garden image-garden.mk the snap and the container bring their own QEMU and tools your host supplies, for ubuntu-cloud-24.04.x86_64 make reads the rules curl fetches the image xorriso packs the seed ISO qemu-img makes the overlay qemu-system-x86_64 boots it OVMF its UEFI firmware in the order make reaches for them, and what it says when one is missing
A native install brings only the image-garden command and image-garden.mk; the snap and the container bring their own tools; for ubuntu-cloud-24.04.x86_64 the host supplies make, curl, xorriso, qemu-img, qemu-system-x86_64 and OVMF, each for one step

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.

Install image-garden from your distribution, or from source, and you get very little: the image-garden command and image-garden.mk, the makefile it runs. The snap and the container carry their own QEMU and tools. A native install borrows yours. So follow ubuntu-cloud-24.04.x86_64 and ask what your machine has to supply. make, to read the rules. curl, to fetch the image. xorriso, to pack the seed. qemu-img, to make the overlay. The x86_64 system emulator, to boot it, and OVMF, the firmware it boots with. This deck takes them in the order make reaches for them, with the message you see when one is missing.

Details and sources

Details

  • 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).
  • The README's comparison says a package or source install uses the system's QEMU, EFI firmware, swtpm, spread and virtiofsd (README.md:96-106), and lists the tools a source build needs (README.md:114-126).
  • The six tools on the slide are what 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.
  • Python is needed only to build image-garden.mk from source, not to run it (derived from Makefile:57-64).

02 Each tool is looked for when its step runs

CHECKED WHEN NEEDED no check up front: each tool is looked up when its step runs download curl curl: not found curl is required the second for a URL from a program seed ISO xorriso program xorriso is required overlay qemu-img program qemu-img is required a missing xorriso shows up after the download; the download is kept install all of them before the first make
No tool is checked up front: the download needs curl, the seed ISO xorriso and the overlay qemu-img, and each missing one stops make only at its own step, with its message; a missing xorriso shows up after the download, which is kept

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.

You might expect make to check for every tool before it starts. It doesn't. Each one is looked up when the first step that needs it runs. curl goes first: the download helper calls it, and without it the shell says curl: not found. Systems whose URL comes from a program say curl is required. Then the seed ISO needs xorriso, and make stops with program xorriso is required. Then the overlay needs qemu-img: program qemu-img is required. So a missing xorriso shows up only after a long download. That download is kept, and the next make carries on from there. Better still, install all of them first.

Details and sources

Details

  • 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).
  • The download helper calls 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).
  • The messages as make prints them: image-garden.mk:LINE: *** program xorriso is required. Stop. (run).
  • Downloads that finished stay in the cache; a later make starts from the next missing file (the target chain).
  • To use a tool outside 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).
  • The firmware copies use $(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.

03 One emulator for each architecture

ONE EMULATOR PER ARCHITECTURE qemu-system-x86_64 qemu-system-aarch64 qemu-system-riscv64 qemu-system-s390x qemu-system-ppc64 qemu-system-loongarch64 qemu-system-x86_64 image-garden.mk:…: program qemu-system-x86_64 is required a warning, then the boot fails: nothing to run all six in the README's list for a source build /dev/kvm exists, but you cannot write to it: WARNING … Please ensure you have write access for much better performance. $ sudo usermod -aG kvm $LOGNAME without KVM every guest is emulated, many times slower
Six system emulators, one per architecture; ubuntu-cloud-24.04.x86_64 needs qemu-system-x86_64; a missing one gives a warning and the boot fails; the README lists all six for a source build; a /dev/kvm the user cannot write gets a large warning that suggests the kvm group

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.

QEMU comes as one system emulator per architecture, and you need only those you'll boot. For ubuntu-cloud-24.04.x86_64 that's qemu-system-x86_64. A missing one is only a warning, program qemu-system-x86_64 is required, printed when make reaches the step that boots it. That boot then fails, because there's nothing to run. There are six in all, one per architecture image-garden knows, and the README lists every one of them. And give yourself /dev/kvm: if it exists but you can't write to it, image-garden make prints a large warning and suggests joining the kvm group, since without it every guest is emulated.

Details and sources

Details

  • Outside the snap, each architecture's emulator is $(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).
  • The README's list for a source build names all six emulators, 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).
  • Without KVM, QEMU emulates the CPU with TCG, "many times slower" (README.md:780-781). Distributions split the emulators into packages differently; Ubuntu's qemu-system-misc, for example, carries loongarch64 (derived; see LoongArch).

04 Firmware, and swtpm for the TPM systems

FIRMWARE AND TPM ubuntu-cloud-24.04.x86_64 OVMF: EDK2 for 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 searched in order, and the same for the variables please install x86_64 edk2 firmware - not in … on every make, even make list-systems ubuntu-core-24+tpm and 3 more swtpm OVMF_CODE_4M.secboot.fd + VARS .ms please install … Secure Boot and Microsoft keys (the ovmf package) swtpm, the TPM emulator, is required: install the swtpm package
An x86_64 UEFI system needs OVMF, looked for in four paths used by Debian, Ubuntu, Arch and openSUSE; without it every make warns please install x86_64 edk2 firmware; the four Ubuntu Core +tpm systems also need the Secure Boot OVMF pair and swtpm, and make stops asking for the ovmf or the swtpm package

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.

Our system boots with UEFI, so it needs EDK2 firmware for x86_64, which your distribution packages as OVMF. image-garden looks in the places Debian, Ubuntu, Arch and openSUSE install it. The other UEFI architectures have their own packages and lists. Until one is installed, every image-garden make warns, please install x86_64 edk2 firmware, and names the places it looked, even when you only list systems. The four Ubuntu Core systems with a TPM need two more things: swtpm, and the Secure Boot build of OVMF. Without them, make stops and asks for the ovmf package, or for the swtpm package.

Details and sources

Details

  • The x86_64 lists, "default location on most Debian/Ubuntu systems, Arch and openSUSE": /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.
  • The first file found is a prerequisite of 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).
  • The +tpm systems take the first complete pair of 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).
  • Their image rule checks 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.
  • "Outside the snap, the host needs swtpm and the ovmf package" (README.md:717-718, README.md:122-126).

05 The small tools, and the optional ones

SMALL TOOLS AND EXTRAS probably there already flock one download at a time sha256sum sha512sum check the hashes shuf, bash, timeout find and probe a free port for allocate unxz Ubuntu Core's .img.xz images optional: no system needs them spread, for spread tests virtiofsd, to share folders a pkgproxy, somewhere $ PKGPROXY_URL=http://pkgproxy.example.lan:3142 image-garden make ubuntu-cloud-24.04.x86_64.run
Small tools image-garden also uses: flock for download locks, sha256sum and sha512sum for hashes, shuf, bash and timeout for allocate's port, unxz for Ubuntu Core; optional extras no system needs: spread, virtiofsd and a pkgproxy named by PKGPROXY_URL

Also used: flock, sha256sum, sha512sum, shuf, timeout, bash, and unxz for Ubuntu Core. Optional: spread, virtiofsd, and a pkgproxy named by PKGPROXY_URL.

The rest you probably have already. image-garden takes a lock on each download with flock, checks hashes with sha256sum and sha512sum, picks a free port for allocate with shuf, and probes it with bash under timeout. Ubuntu Core images come compressed, so those need unxz too. Then there are the extras, which no system needs. spread is a package of its own, if you run spread tests. virtiofsd is the system's, if you share directories with guests. And pkgproxy isn't bundled: run one somewhere and name it with PKGPROXY_URL, and the downloads and the guests' packages go through it.

Details and sources

Details

  • Each download helper locks 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).
  • Ubuntu Core images are .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.
  • The README's comparison: spread "No (use system package)", virtiofsd "System package", pkgproxy "With 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.

06 Where to go from here

ROADS Host tools Installing from source what make install puts where Distribution packages which version you have The distribution QEMU no patch, PKGPROXY_URL UEFI firmware every search list Secure Boot and TPM the four +tpm systems Architectures machines, KVM and TCG
Six roads from Host tools: installing from source, distribution packages, the distribution QEMU, UEFI firmware, the TPM systems and the architectures

Next: installing from source, distribution packages, the distribution QEMU, firmware, the TPM systems and the architectures.

That's the whole list: make, curl, xorriso and qemu-img, an emulator for each architecture you boot, its firmware, and swtpm for the TPM systems. If you're building from source, the source deck shows what make install puts where. If you took a package, its deck says how to check which version you have. The deck on the distribution QEMU covers what you give up without the snap's patch. And the firmware, TPM and architecture decks go deeper into each of those.

Details and sources

Read more

Basis of the statements on this page

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".

Host tools by step

ToolNeeded forOverrideWhen it is missing
makeeverything: image-garden make runs itthe shell's "not found"
curlchecksum lists and images; URLProgram systemsCURL (URLProgram only)curl: not found from the download helper; curl is required for Amazon Linux and Gentoo
xorrisothe cloud-init seed ISOXORRISOprogram xorriso is required
qemu-imgthe overlay, firmware copies, unpacked images, rebaseQEMU_IMGprogram qemu-img is required
qemu-system-ARCHthe provisioning boot and the .run scriptQEMU_SYSTEM_X86_64 and siblingswarning program qemu-system-ARCH is required, then the boot fails
EDK2 firmwaresystems with Boot=efiQEMU_EDK2_CODE_ARCH, QEMU_EDK2_VARS_ARCH, GARDEN_ARCH_PREFIXwarning please install ARCH edk2 firmware - not in … on every make
Secure Boot OVMF pairthe four +tpm systemsQEMU_EDK2_SECBOOT_CODE_X86_64, …_VARS_X86_64please install x86_64 edk2 firmware with Secure Boot and Microsoft keys (the ovmf package)
swtpmthe four +tpm systemsSWTPMswtpm, the TPM emulator, is required: install the swtpm package
unxzUbuntu Core .img.xz imagesthe shell's "not found"
flock, sha256sum, sha512sumdownload locks and checksthe shell's "not found"
shuf, timeout, bashallocate'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.

Emulators by architecture

ArchitectureEmulatorFirmware
x86_64qemu-system-x86_64OVMF (EDK2) for efi systems; none for bios
aarch64qemu-system-aarch64AAVMF (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
riscv64qemu-system-riscv64EDK2 for RISC-V
loongarch64qemu-system-loongarch64EDK2 for LoongArch
s390xqemu-system-s390xnone
ppc64qemu-system-ppc64none

The search lists for every architecture are in UEFI firmware per system.

Optional

ExtraWhat forWhere it comes from
spreadrunning spread tests against garden systemsa system package
virtiofsdsharing a host directory with a guesta system package
pkgproxycaching images and guest packagesanywhere reachable; name it with PKGPROXY_URL
write access to /dev/kvmKVM instead of emulationthe kvm group on most distributions

Roads from here

UBUNTU CORE · all snaps

ARCHITECTURES · machines and firmware

NATIVE · packages