image-garden - Man Page

The image-garden make sub-command allows building one or more goals corresponding to virtual machine images and their support files.

The following goals are documented. Note that ARCH and SYSTEM are placeholders for CPU architecture as named by the Linux kernel and standardized distribution name, respectively. Please see the table for a complete list of valid SYSTEM-ARCH combinations.

help

Display help message specific to the set of make rules contained within image-garden

all

Build all of the images for the native CPU architecture.

fetch

Fetch all the base cloud images or installers, so that further work can be done mostly offline. The only exception is installation if packages described by per-project cloud-init profiles.

clean

Remove all the generated disk images from the current directory.

distclean

Remove all the base cloud images and installer images from the per-user cache directory.

$SYSTEM.$ARCH.qcow2

qemu disk image of operating system $SYSTEM for CPU architecture $ARCH. Cloud disks contain internal reference to base image stored in per-user cache directory. Both files are required at runtime.

$SYSTEM.$ARCH.qcow2.log

Serial console output collected during first boot of the machine.

$SYSTEM.$ARCH.run

Shell script for running the virtual machine. This script supports extensive customization through environment variables and command line arguments. Command line arguments are passed directly to image-garden qemu-system-$ARCH . Recognized environment variables are described in a dedicated section below.

$SYSTEM.$ARCH.efi-code.img

Symbolic link to efi-code.$ARCH.img.

$SYSTEM.$ARCH.efi-vars.img

Disk image with current state of the boot firmware corresponding to $SYSTEM.$ARCH.qcow2.

$SYSTEM.seed.iso

ISO 9660 disk image with cloud-init files used during first boot.

$SYSTEM.user-data

Text of the cloud-init user data. This file exists briefly as a prerequisite for $SYSTEM.seed.iso.

$SYSTEM.meta-data

Text of the cloud-init meta data. This file exists briefly as a prerequisite for $SYSTEM.seed.iso.

efi-code.aarch64.img

Disk image of EFI firmware for aarch64 CPU architecture.

efi-vars.aarch64.img

Disk image of with the unmodified state of EFI firmware for the aarch64 CPU architecture.

efi-code.x86_64.img

Disk image of EFI firmware for the x86_64 CPU architecture.

efi-vars.x86_64.img

Disk image of with the unmodified state of EFI firmware for the x86_64 CPU architecture.

Systems are identifiers for a particular operating system, variant, release and CPU architecture. The following list contains all the systems recognized by image-garden.

almalinux-cloud-{8,9}

Alma Linux cloud images.

alpine-cloud-3

Alpine Linux cloud image.

archlinux-cloud

Arch Linux cloud image. This system is only supported on the x86_64 CPU architecture.

centos-cloud-{9,10}

CentOS cloud images (usually CentOS stream).

debian-cloud-{10,11,12,13}

Debian cloud images.

fedora-cloud-{38,39,40,41}

Fedora cloud images.

opensuse-cloud-{15.4,15.5,15.16,tumbleweed}

openSUSE cloud images.

oracle-cloud-{8,9}

Oracle Linux cloud images.

rocky-cloud-{8,9}

Rocky Linux cloud images.

ubuntu-cloud-14.04

This system fails to boot correctly.

ubuntu-cloud-{16,18,20,22,24}.04

Ubuntu Long Term Support (LTS) cloud images.

ubuntu-cloud-{24.10,25.04}

Ubuntu development releases cloud images.

XDG_CACHE_HOME

Directory with per-user cache files that may be safely deleted. According to the specification the default value is "$HOME/.cache".

GARDEN_CACHE_DIR

Directory with non-essential files that can be reused across projects. The default value is "$XDG_CACHE_HOME/image-garden".

GARDEN_DL_DIR

Directory where downloaded operating system images are stored. Those images may be sizable so care needs to be taken to avoid using excessive amount of disk space. All the images stored here are used in read-only mode and are automatically shared by different project developed by the same user. The default value is "$GARDEN_CACHE_DIR/dl".

QEMU_MEM_SIZE

Amount of memory, in megabytes, to provide to each virtual machine. This value is copied into the generated $SYSTEM.run scripts. The default value is "2048", for 2GB of runtime memory. Not to be confused with similarly-named QEMU_MEM_OPTION.

QEMU_IMG_SIZE

Size of the virtual disk image created by qemu-img(1) when invoked from image-garden. The default value is "64G". Note that images use a format with internal representation of sparse areas. The required disk space is much smaller than this size.

QEMU_SMP_X86_64

The number of virtual CPU cores for virtual machines emulating the x86_64 CPU architecture. The default value is "4" when the CPU architecture of the host and the guest are the same or "1" otherwise. Not to be confused with similarly-named QEMU_SMP_OPTION.

QEMU_SMP_AARCH64

The number of virtual CPU cores for virtual machines emulating the aarch64 CPU architecture. The default value is "4" when the CPU architecture of the host and the guest are the same or "1" otherwise. Not to be confused with similarly-named QEMU_SMP_OPTION.

QEMU_SYSTEM_X86_64

Full path of the qemu-system-x86_64 program to use instead of the one found on PATH.

QEMU_SYSTEM_AARCH64

Full path of the qemu-system-aarch64 program to use instead of the one found on PATH.

QEMU_IMG

Full path of the qemu-img program to use instead of the one found on PATH.

MKPASSWD

Full path of the mkpasswd program to use instead of the one found on PATH.

GENISOIMAGE

Full path of the genisoimage program to use instead of the one found on PATH.

WGET

Full path of the wget program to use instead of the one found on PATH.

XDG_RUNTIME_DIR

Directory with per-user runtime files that do not persist across reboots. According to the specification the default value is "/run/user/$UID". The image-garden program, when used as a back-end for the spread(1) test system uses this directory to keep track of running virtual machines and their TCP port numbers.

The following environment variables are used by generated .run scripts.

QEMU_MEM_OPTION

Memory configuration options to pass to qemu. Example value is "-m 1024".

QEMU_SMP_OPTION

CPU topology options to pass to qemu. When unset the default value is "-smp $QEMU_SMP_$(uname -m)". Example value is "-smp $(nproc)".

QEMU_DISPLAY_OPTION

Graphical display options to pass to qemu. When unset the default value is "-nographic". Example value is "-display gtk".

QEMU_BOOT_FIRMWARE_OPTION

Boot firmware options to pass to qemu. The default value depends on the requirement of the booted system. For systems booting with EFI a pair of "-drive pflash" arguments is used for representing EFI code and EFI variables. For systems booting with legacy BIOS no options are provided.

QEMU_RNG_OPTION

Random-number configuration options to pass to qemu. When unset the default value is "-device virtio-rng-pci"

QEMU_NET_OPTION

Network configuration options to pass to qemu. When unset the default value is "-netdev user,id=netdev0${QEMU_NETDEV_USER_EXTRA:-} -device virtio-net-pci,netdev=netdev0,id=net0 -smbios type=41,designation=Virtual-LAN,instance=1,kind=ethernet,pcidev=net0"