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
- Snap, container or native package — what the snap and the container would bring instead
01 Everything but the script comes from your host
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 installinstalls theimage-gardenscript,image-garden.mk, the README and NEWS files and the man page, nothing else (Makefile:30-46);image-garden makeruns the host'smakeon 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.runneeds 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.mkfrom source, not to run it (derived from Makefile:57-64).
02 Each tool is looked for when its step runs
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))andCURL ?= $(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 fromPATH:image-garden make list-systemssucceeded 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 theURLProgramof Amazon Linux and Gentoo (data/gentoo.ini:9).- The download helper calls
curlitself, not$(CURL)(image-garden:110-119). Run without curl, it printed…/image-garden: 118: curl: not foundand make stopped withError 127(run,/bin/shbeing 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, setXORRISO,CURLorQEMU_IMG(README.md:917-921). SettingCURLreplaces 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 doesimage-garden rebase, which readsQEMU_IMGfrom the environment (image-garden:970-980); one setting moves everyqemu-imgcall.
Read more
03 One emulator for each architecture
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.runscript), twice per recipe (run on a host withoutqemu-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,-ppc64and-loongarch64, "or the emulators of the architectures you use" (README.md:122-126). kvm_check, run byimage-garden makeandallocate, prints a large WARNING when/dev/kvmexists but is not writable, then suggestssudo usermod -aG kvm $LOGNAME, or, withCIset,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).
Read more
04 Firmware, and swtpm for the TPM systems
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, soimage-garden make list-systemsprinted one warning per list for every UEFI architecture without firmware (run). - The +tpm systems take the first complete pair of
OVMF_CODE_4M.secboot.fdandOVMF_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
swtpmand theovmfpackage" (README.md:717-718, README.md:122-126).
Read more
05 The small tools, and the optional ones
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.lockwithflock 9(image-garden:374, :476, :583) and checks withsha512sum --checkorsha256sum --check(image-garden:442, :544). The unpack and convert rules lock withflocktoo (mk/010-qemu.mk:321-332). allocatepicks a port withshuf -i 5000-9999 -n 1(image-garden:1100) and probes it with bash's/dev/tcpundertimeout: "bash and timeout are essential packages" (image-garden:790-822).- Ubuntu Core images are
.img.xz, unpacked withunxz(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_URLmust behttp://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
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
| 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.
Emulators by architecture
| 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.
Optional
| 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 |
Roads from here
UBUNTU CORE · all snaps
- Ubuntu Core with Secure Boot and a TPM — the +tpm systems that need swtpm and the Secure Boot pair
ARCHITECTURES · machines and firmware
- UEFI firmware per system — every firmware search list and override
- Six architectures, six QEMU machines — the machine, CPU and accelerator behind each emulator
NATIVE · packages
- Installing from source — build and install image-garden itself
- Distribution packages — the distribution packages and how to check their version
- Living with the distribution QEMU — what running your distribution's QEMU means