The .run script
QEMU_*_OPTION for users
X.run is a readable bash script holding the exact QEMU command for one system. QEMU_*_OPTION environment variables replace its defaults, extra arguments go to QEMU, it boots in the foreground and keeps its changes unless you add -snapshot.
On the map: runtime
▶ Watch this deck — 7 scenes, ~5 min
Worth seeing first
- From a system's name to a running VM — where the .run script comes from
Part of journeys
- Your first garden VM, step 3 of 4 · previous: image-garden make and the other commands · next: Working on the serial console
02 What is inside
set -xeu, the --query preamble, a default for each QEMU_*_OPTION, then read -ra into an array, "$@" on the end, and exec.
The script has four parts. It starts by turning on bash's trace mode, so bash prints every command before running it, and you see the full QEMU line on your terminal. Next comes the query part, which answers questions about the system and exits. Then the defaults: one variable per group of options, memory, CPUs, display, firmware, storage, random numbers and network. Each one is used only if you haven't set it already. Finally the script splits those strings into words, builds the QEMU command as a bash array, adds any arguments you gave it, and runs QEMU in its place.
Details and sources
Details
- The script starts with
#!/bin/bashandset -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). - The
--queryblock printsvm.memory_mband the users, then exits (010-qemu.mk:63-92). - One
default_qemu_*_optionline per group, then: "${QEMU_X_OPTION:=$default…}", which keeps a value you set (010-qemu-x86_64.mk:62-80). read -rasplits each string into an array, the command is built asqemu_cmd,"$@"is appended (010-qemu-x86_64.mk:82-105), andexec "${qemu_cmd[@]}"replaces the script with QEMU (010-qemu-x86_64.mk:110-113).- A +tpm system's script also starts swtpm and does not
exec; see swtpm per launch.
Read more
03 Change it without editing it
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.
You rarely need to edit the script. Each group of options has an environment variable, and setting it replaces that whole group. QEMU_MEM_OPTION set to -m 4096 gives the machine four gigabytes instead of two. QEMU_SMP_OPTION changes the number of CPUs, and QEMU_DISPLAY_OPTION set to -display gtk opens a window instead of using your terminal. Anything you pass after the script's name goes to QEMU as it is, on the end of the command. That's how you add a device, share a directory, or ask for a snapshot, without touching the file make wrote.
Details and sources
Details
- The variables are
QEMU_ACCEL_MACHINE_PROP,QEMU_MEM_OPTION,QEMU_SMP_OPTION,QEMU_DISPLAY_OPTION,QEMU_BOOT_FIRMWARE_OPTION,QEMU_STORAGE_OPTION,QEMU_RNG_OPTIONandQEMU_NET_OPTION, andQEMU_TPM_OPTIONfor the +tpm systems (010-qemu-x86_64.mk:72-80). Setting one replaces its whole group, soQEMU_BOOT_FIRMWARE_OPTIONorQEMU_STORAGE_OPTIONmust name the files again. - The memory default is
-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). - The README lists the same variables,
QEMU_NET_OPTION,QEMU_STORAGE_OPTION,QEMU_TPM_OPTIONandQEMU_ACCEL_MACHINE_PROPamong them, andQEMU_NETDEV_USER_EXTRA, which is added to the default-netdev useroption 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.
Read more
- The full table of variables and defaults is in the reading below the deck.
04 Boot it and log in
Run ./ubuntu-cloud-24.04.x86_64.run and log in at the prompt as ubuntu/ubuntu or root/root.
Now run it. The script stays in the foreground, and after a screen of firmware and kernel messages you get a login prompt, right there in your terminal. The image was prepared with two accounts: root with the password root, and a user named after the distribution, so ubuntu with the password ubuntu here, who can use sudo without a password. Log in as either one and the machine is yours. It has network access through QEMU, so you can install packages and fetch things as you would on any other machine.
Details and sources
Details
- The quick start: run the script in the foreground, it boots to a login prompt, log in as
ubuntu/ubuntuorroot/root(README.md:77-79). - The accounts come from the common user-data:
rootwithplain_text_passwd: rootand a user named after the group, with the same password andsudo: ["ALL=(ALL) NOPASSWD:ALL"](010-qemu.mk:200-214). - The hostname is group and release with dots turned into dashes,
ubuntu-24-04here (010-qemu.mk:196). - Network: QEMU user networking with a virtio network card (010-qemu-x86_64.mk:8-11).
- The trace line and the prompt on the slide are drawn from the script and the hostname rule, not captured from a run.
Read more
05 Kept or thrown away
Changes go into ubuntu-cloud-24.04.x86_64.qcow2 and stay. With -snapshot they are thrown away when QEMU exits.
By default, everything you change is kept. The script boots the prepared overlay itself, so a package you install now is there next time, and in every machine made from this file later, including the ones allocate starts. Sometimes that's what you want. When it isn't, pass -snapshot to the script. QEMU then keeps every write in a temporary file and drops it when the machine stops, so the image on disk stays exactly as make left it. That's also what allocate does for you, every time.
Details and sources
Details
- "The VM runs with persistent storage by default. Pass -snapshot to the
.runscript to make each invocation ephemeral" (README.md:85-86). - The script boots
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-snapshotis in every machine allocated later (derived). - allocate adds
-snapshotunlessQEMU_SNAPSHOT_OPTIONis set (image-garden:1154). - To start again from a clean prepared image, remove
X.qcow2and make it again.
Read more
06 Shutting down
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.
When you're done, shut the machine down from inside, with sudo shutdown -h now. The guest powers off, QEMU exits, and you're back at your own prompt. Because the script runs QEMU in its own place, there's nothing left behind. One thing a machine started this way can't do is take an SSH connection: no port on your host leads to it. If you'd rather work over SSH, or start a machine in the background for tests, that's what image-garden allocate is for.
Details and sources
Details
- "From inside VM: sudo shutdown -h now" (README.md:81-82).
- The script
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. - "Note that you cannot use ssh to connect to a machine that was started with the run script" (README.md:86-89): the SSH port forward is added only by allocate, through
QEMU_NETDEV_USER_EXTRA(image-garden:1107).
Read more
07 Where to go from here
Next: the serial console, image-garden allocate, and --query.
So the .run script is the whole machine in one readable file: defaults you can override, arguments that go straight to QEMU, and a disk that keeps its changes unless you ask for a snapshot. Next, see what the terminal is like when it's the machine's serial console, because it behaves a little differently. Then meet allocate, which runs the same script in the background with SSH. And if a tool needs to know the users and the memory, there's the query option.
Details and sources
Details
- The script, its variables and its arguments, as covered in this deck, apply to every system; the +tpm systems add swtpm.
Read more
Read more
Basis of the statements on this page
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.
The variables of an x86_64 .run script
| 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.
Variables that are not options
| 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 |
Arguments
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.
Roads from here
RUNTIME · make rules and the CLI
- Working on the serial console — what to expect from the terminal it runs in
- image-garden allocate — the same script in the background, with SSH
- Asking a .run script about its system — what the script tells tools about its system
- The overlay and the provisioning boot — the disk the script boots
FIRST BOOT · cloud-init changes
- The users every system gets — the users and passwords you log in with