Getting started

In this short howto you will learn how to import an example configuration and build it.

The build process is described in a file named build.xml.

This file points to the build-vm, which is a virtual machine used for bootstrapping the target-vm - the virtual machine we would like to build. Both build-vm and target-vm configuration directives need a name, an arch (architecture) and version.

A list of jobs describes, how the target-vm is bootstrapped and what commands to run as the target-vm in the form of run-jobs.

At the end of the build process the path to the raw image of the target-vm is printed out, so you can use it with your virtual machine manager of choice.

Using examples

  • Make sure the following binaries are available from your package manager

    • On GNU Linux:
      • qemu package providing:
        • /usr/share/qemu/bios-microvm.bin
        • /usr/share/qemu/bios.bin
        • qemu-system-x86_64 executable
      • seabios package providing (if qemu does not ship with the bios binaries):
        • /usr/share/seabios/bios-microvm.bin
        • /usr/share/seabios/bios.bin
    • On FreeBSD:
      • bhyve-firmware package providing:
        • /usr/local/share/uefi-firmware/BHYVE_UEFI.fd
      • libslirp package providing:
        • userspace networking for bhyve
    • On NetBSD:
      • qemu package providing:
        • /usr/share/qemu/bios-microvm.bin
        • /usr/share/qemu/bios.bin
        • qemu-system-x86_64 executable
    • On DragonflyBSD:
      • qemu package providing:
        • /usr/share/qemu/bios-microvm.bin
        • /usr/share/qemu/bios.bin
        • qemu-system-x86_64 executable
    • On OpenBSD:
      • already included:
        • vmctl executable
    • On Apple MacOS:
      • VirtualBox package (see: https://www.virtualbox.org/wiki/Downloads) providing:
        • VBoxManage executable
    • On Microsoft Windows:
      • qemu package providing:
        • /usr/share/qemu/bios-microvm.bin
        • /usr/share/qemu/bios.bin
        • qemu-system-x86_64 executable
      • m̀sys2 package providing:
        • /usr/bin/bash.exe to call vm-builder from
        • providing the XDG_RUNTIME_DIRS environment variable to find:
          • /usr/share/qemu/bios-microvm.bin
          • /usr/share/qemu/bios.bin
    • On Sculpt OS (Genode microkernel framework):
      • vbox5 package providing
        • virtualbox
      • nic_bridge package providing
        • nic_bridge (for network between proxy-vm and target-vm)

  • If qemu is used as the VMM of choice, please make sure the XDG_RUNTIME_DIRS environment variable is set, so vm-builder can find the files:

  • /usr/share/qemu/bios-microvm.bin

  • /usr/share/qemu/bios.bin

  • Continue by cloning the vm-builder repository, which includes both a reference build-vm, as well as example build configuration files for GNU Linux, FreeBSD and Microsoft Windows, OpenBSD, NetBSD, DragonflyBSD, NixOS and MacOS:

git clone https://codeberg.org/uvm/vm-builder.git
  • If not done already, change into the repositories directory and install vm-builder:
cd vm-builder
cargo install --path .
  • Check that vm-builder is properly installed by printing it's help text:
vm-builder --help
  • The examples are located in the repositories examples directory. Let's first import the example vm-repo repository including the build-vm, which we use for bootstrapping the other target-vms:
vm-builder import --path import.xml
  • Now we can build the other build configurations als residing in the examples directory. They are already imported by above command. We can build them as well:
vm-builder build --repo vm-repo --arch x86_64 --name linux-alpine-v3.13 --version 2024-04-13
vm-builder build --repo vm-repo --arch x86_64 --name freebsd-13.0 --version 2024-04-13
vm-builder build --repo vm-repo --arch x86_64 --name windows-10-21H2 --version 2024-04-13
vm-builder build --repo vm-repo --arch x86_64 --name nixos --version 2024-07-23
  • In order to build all configurations, just ommit the --arch, --name and --version filters:
vm-builder build --repo vm-repo
  • To conveniently build all configurations which have not been build successfully yet:
vm-builder build --repo vm-repo -f -i

Storage paths

vm-builder by default stores it's files in the current users home directory under ~/.uvm.

Build configurations are found in ~/.uvm/configs and images in ~/.uvm/images.

This can be overriden by the following environment variables:

  • VMBUILDER_REPO_PATH - where to store imported build configurations
  • VMBUILDER_IMAGE_PATH - where to store built images