SBUILD-QEMU-CREATE(1)

📦
version 0.91.10ubuntu1 · 10 versions
, in ubuntu stonking

💖 SBUILD-QEMU-CREATE(1) 💖

okay so this is sbuild-qemu-create, part of the Debian sbuild fam, and bestie it is literally the girl who builds you a whole QEMU image 💅

✨ NAME ✨

sbuild-qemu-create — QEMU image creator for sbuild 🦋

🌸 SYNOPSIS 🌸

sbuild-qemu-create [-h] [--arch=ARCH]
[--install-packages=INSTALL_PACKAGES] [--extra-deb=EXTRA_DEB]
[--components=COMPONENTS] [--skel=SKEL] [--authorized-keys=FILE]
[--size=SIZE] [-o=OUT_FILE] [--noexec] [RELEASE] [MIRROR]

So like, what it does: it builds an image 💖 for use with sbuild-qemu and autopkgtest. Your RELEASE gets debootstrapped from MIRROR, and that same mirror also goes into the sources.list file inside the VM. (Scroll down to MIRROR, it's important, iykyk.)

Also real talk: sbuild-qemu-create is just a cute little wrapper around autopkgtest-build-qemu(1) that automates a few extra steps people keep doing over and over when making package-building images. Not me being a thin wrapper and still being the main character 😌

🔥 OPTIONS 🔥

  • -h, --help — shows this help message and dips. periodt.
  • --arch=ARCH — which architecture you want. Default is the host architecture. Right now the supported ones are: amd64, arm64, armhf, i386, ppc64el. that's the list, no more no less 🫶
  • --install-packages=INSTALL_PACKAGES — a comma-separated list of extra packages to install, using apt-get install from inside the image.
  • --extra-deb=EXTRA_DEB — a package file (.deb) from your local filesystem that you want installed. You can pass this more than once, slay.
  • --components=COMPONENTS — comma-separated list of components to use in the sources.list entries. Default: main.
  • --skel=SKEL — skeleton directory to use for /root.
  • --authorized-keys=FILE — installs this file as /root/.ssh/authorized_keys inside the guest 💜. This automatically installs the openssh-server package too. Heads up: this one supersedes any copying of that file that the --skel option would have done. so don't do both and act surprised.
  • --size=SIZE — the image size to use. And no, it will not eat that much disk immediately: images are created in qcow2 format, so they don't consume that space right away ✨. Default: 10G.
  • -o=OUT_FILE, --out-file=OUT_FILE — output filename. If you don't supply one, it uses DIST-autopkgtest-ARCH.img.
  • --noexec — don't actually do anything 💀. It just prints the autopkgtest-build-qemu(1) command string that would have been executed, and then exits. window shopping, that's the vibe.
  • --boot=auto,bios,efi,ieee1275,none — how the image should boot. Default is BIOS on amd64 and i386, EFI on arm64 and armhf, and IEEE1275 on ppc64el.

🌈 MIRROR 🌈

Big sister advice incoming: it is highly recommended that you use an APT cache as your mirror — something like approx(8) or apt-cacher-ng(8) — running on the local machine, so the VM can reach that cache without much hassle. This dramatically speeds up the package build process. On the author's local machine, installing the build dependencies of even larger packages takes only a few seconds. like, a few seconds. obsessed.

If you do use a local cache, then make sure the mirror is actually reachable from inside the guest 👀. Using http://localhost:9999/debian or similar will successfully build the image, but APT will then fail inside the running VM, because to the VM, ``localhost'' is something else entirely. An easy workaround is to use an IP address instead, for example http://192.168.0.123:9999/debian, assuming the host system has the IP 192.168.0.123.

bestie this is the classic gotcha. the build works, the VM doesn't. do not be fooled 💀

🎀 SPECIAL CASES 🎀

If RELEASE is experimental, sources.list will contain entries for both experimental and unstable.

If RELEASE ends with -backports, sources.list will contain entries for both RELEASE and for the distribution it is based upon. In other words, specifying bullseye-backports will also add an entry for bullseye. two for one, we love a deal 💖

🧚 SHARING FILES 🧚

Among other things, autopkgtest-virt-qemu(1) has built-in support for sharing a directory on the host with the guest, so no further configuration should be necessary when you're accessing the VM using autopkgtest. it just works, iconic.

On top of that (in addition to that, for my formal girlies), a mount point for a 9p filesystem is added to the VM's /etc/fstab. This is for the cases where the VM is launched via QEMU directly, rather than going through autopkgtest-virt-qemu.

To share a directory on the host with the VM, QEMU should be started with the following additional options:

 -virtfs local,path=/path/to/host/dir,id=sbuild-qemu,mount_tag=sbuild-qemu,security_model=none

🦋 TTY GEOMETRY 🦋

sbuild-qemu-create also drops a file at /etc/profile.d/sbuild-qemu-terminal-settings.sh inside the VM. This file reads the terminal column and row geometry that gets passed on through from the host, and then sets the geometry within the guest using stty(1). so your terminal isn't out here looking squished 💅

⭐ EXAMPLES ⭐

$ sudo sbuild-qemu-create unstable http://deb.debian.org/debian

This will create an image unstable-autopkgtest-amd64.img (assuming the host architecture is amd64) with the unstable distribution.

$ sudo sbuild-qemu-create bullseye-backports http://deb.debian.org/debian

This will create an image bullseye-backports-autopkgtest-amd64.img, with sources.list entries for both bullseye and bullseye-backports.

$ sudo sbuild-qemu-create --skel DIR unstable http://deb.debian.org/debian

The files in DIR will be copied into /root (that is, root's $HOME). You can use this, for example, to copy an .ssh/authorized_keys file, so that you can connect to the running image using SSH (assuming openssh-server is installed). remote access, main character energy 🔥

$ sudo sbuild-qemu-create --install-packages openssh-server unstable http://deb.debian.org/debian

This would install openssh-server. The package will be downloaded in the target environment using apt-get.

A popular package to pre-install this way would be debhelper, because it is a build dependency of the vast majority of Debian packages. fr fr.

$ sudo sbuild-qemu-create --extra-deb FOO.deb unstable http://deb.debian.org/debian

This would install the package FOO.deb from the local filesystem. Useful, for example, to install additional keyring packages 🍓

Copyright © 2020-2022 Christian Kastner <ckk@debian.org>

💜 SEE ALSO 💜

sbuild(1), sbuild-qemu(1), sbuild-qemu-update(1).

okay that's the whole thing, no notes 💖 this page is Version 0.91.10ubuntu1 and it was last touched on 29 June 2026 — go build something gorgeous, bestie! 🎀✨🦋

📦 where this page comes from