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

Part of journeys

01 A script you can read

THE .RUN SCRIPT a typical VM tool the command stays hidden ubuntu-cloud-24.04.x86_64.run #!/bin/bash set -xeu qemu_cmd=("qemu-system-x86_64") qemu_cmd+=(-cpu max) … exec "${qemu_cmd[@]}" what is inside change it, don't edit it kept or thrown away
A typical VM tool hides its command; image-garden's ubuntu-cloud-24.04.x86_64.run is plain bash that ends in the exact QEMU command; the deck covers what is inside, how to change it without editing, and what happens to the disk

The .run script is plain bash with the exact QEMU command for one system. Read it, copy it, or change it through environment variables.

Most tools that start virtual machines hide the command they run. You get a button or a subcommand, and when you want more memory or an extra device, you go hunting for the right flag. image-garden goes the other way. The last file make writes for a system, such as Ubuntu 24.04 on x86, is a .run script, and it's plain bash. Open it in an editor and you'll see the exact QEMU command it runs, with every default spelled out. This deck walks through that script: what's inside, how to change it without editing it, and what happens to the disk when you boot it.

Details and sources

Details

02 What is inside

INSIDE THE SCRIPT set -xeu trace: bash prints each command if [ "${1:-}" = "--query" ]; then … answer questions, then exit default_qemu_mem_option="-m 2048" : "${QEMU_MEM_OPTION:=$default_qemu_mem_option}" one default per option group used only if you set nothing read -ra QEMU_MEM_OPTION <<<"$QEMU_MEM_OPTION" qemu_cmd+=("$@") split into words, build an array your arguments go on the end exec "${qemu_cmd[@]}" QEMU takes the script's place
The script in five bands: set -xeu traces every command; --query answers and exits; a default for each QEMU option group used unless already set; read -ra into an array with the caller's arguments appended; exec replaces the script with QEMU

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/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).
  • The --query block prints vm.memory_mb and the users, then exits (010-qemu.mk:63-92).
  • One 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).
  • A +tpm system's script also starts swtpm and does not exec; see swtpm per launch.

03 Change it without editing it

CHANGE IT WITHOUT EDITING IT QEMU_MEM_OPTION replaces the whole group $ QEMU_MEM_OPTION="-m 4096" ./ubuntu-cloud-24.04.x86_64.run $ QEMU_SMP_OPTION="-smp 4" ./ubuntu-cloud-24.04.x86_64.run $ QEMU_DISPLAY_OPTION="-display gtk" ./ubuntu-cloud-24.04.x86_64.run $ ./ubuntu-cloud-24.04.x86_64.run -snapshot arguments after the name are added to the end of the QEMU command the file make wrote stays as it was
Setting QEMU_MEM_OPTION replaces the default -m 2048; examples set memory, CPUs and a gtk display through environment variables, and -snapshot after the script name is appended to the QEMU command; the file make wrote is not edited

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_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.
  • 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_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.

Read more

  • The full table of variables and defaults is in the reading below the deck.

04 Boot it and log in

BOOT IT AND LOG IN $ ./ubuntu-cloud-24.04.x86_64.run + exec qemu-system-x86_64 -cpu max … … firmware and kernel messages … ubuntu-24-04 login: root / root ubuntu / ubuntu sudo without a password ubuntu Password: ubuntu@ubuntu-24-04:~$ network through QEMU
Running the script in a terminal prints the traced QEMU command, then firmware and kernel messages, then a login prompt for host ubuntu-24-04; two accounts exist, root with password root and ubuntu with password ubuntu and passwordless sudo; the machine has network through QEMU

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/ubuntu or root/root (README.md:77-79).
  • The accounts come from the common user-data: 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).
  • The hostname is group and release with dots turned into dashes, ubuntu-24-04 here (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.

05 Kept or thrown away

KEPT OR THROWN AWAY $ ./ubuntu-cloud-24.04.x86_64.run the download ubuntu-cloud-24.04.x86_64.qcow2 the prepared overlay kept: the next boot sees it, and every machine allocate starts $ ./ubuntu-cloud-24.04.x86_64.run -snapshot a temporary file dropped at exit the image stays as make left it allocate always boots with -snapshot
Running the script writes changes into the prepared overlay ubuntu-cloud-24.04.x86_64.qcow2, where later boots and allocated machines see them; with -snapshot QEMU keeps writes in a temporary file that is dropped when it exits, leaving the image as make left it; allocate always uses -snapshot

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 .run script 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 -snapshot is in every machine allocated later (derived).
  • allocate adds -snapshot unless QEMU_SNAPSHOT_OPTION is set (image-garden:1154).
  • To start again from a clean prepared image, remove X.qcow2 and make it again.

06 Shutting down

SHUTTING DOWN ubuntu@ubuntu-24-04:~$ sudo shutdown -h now the guest powers off QEMU exits you are at your own prompt ssh from the host no port on the host leads to it image-garden allocate in the background, with SSH
Typing sudo shutdown -h now in the guest powers it off, QEMU exits and you are back at your prompt; a machine started by its .run script has no SSH port on the host; image-garden allocate gives one

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

07 Where to go from here

ROADS The .run script The serial console why the terminal acts oddly image-garden allocate background, with SSH --query users and memory for tools
Three roads from The .run script: the serial console, image-garden allocate and the --query option

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

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

VariableDefaultWhat it sets
QEMU_ACCEL_MACHINE_PROP,accel=kvm:tcg when QEMU lists kvm, else ,accel=tcgappended to -machine q35
QEMU_MEM_OPTION-m 2048memory
QEMU_SMP_OPTION-smp 4 on an x86_64 host, -smp 1 elsewhereCPUs
QEMU_DISPLAY_OPTION-nographic (allocate: -display none)display and console
QEMU_BOOT_FIRMWARE_OPTIONtwo -drive if=pflash lines: the read-only EFI code and the system's writable variable storefirmware
QEMU_STORAGE_OPTION-drive file=X.qcow2,…,cache=writeback,discard=unmap -device virtio-blk,…,bootindex=0the disk
QEMU_RNG_OPTION-device virtio-rng-pcirandom numbers
QEMU_NET_OPTION-netdev user,id=netdev0… with virtio-net-pcinetwork
QEMU_TPM_OPTION+tpm systems only: -chardev socket…, -tpmdev emulator…, -device tpm-crbTPM

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

VariableEffect
QEMU_NETDEV_USER_EXTRAappended to -netdev user; allocate puts the SSH hostfwd here
QEMU_SNAPSHOT_OPTIONread 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

FIRST BOOT · cloud-init changes