DEBVM-CREATE(1)

📦
version 0.5.2ubuntu1 · 5 versions
, in ubuntu resolute, ubuntu stonking

✨ DEBVM-CREATE(1) ✨

okay so bestie, you know how debvm-create is a thing in the Perl docs section? yeah. this is that. it's a whole vibe and we're gonna go through it together 💖

🌸 NAME 🌸

debvm-create — Create a VM image for various Debian releases and architectures

like. that's literally what it does. it makes you a lil baby VM image and it does NOT care which release or which arch you want, it's flexible like that 🦋

🎀 SYNOPSIS 🎀

debvm-create [-h hostname] [-k sshkey] [-o output] [-r release] [-s <task>] [-z size] [-- mmdebstrap options]

that's the whole shape of it. short flags, some values, and then a double dash so you can pass stuff straight down to mmdebstrap. iconic honestly.

💅 DESCRIPTION 💅

So debvm-create is essentially a thin wrapper around mmdebstrap, right? It's out here creating a raw ext4 filesystem image that you can boot with debvm-run. That's the whole point 🫶

And the purpose of these images? primarily testing the different releases and architectures without access to a physical machine of that architecture. That's the dream, no cap — you don't need to own the hardware to test on the hardware. slay.

Beyond the essential packages, the image is gonna contain:

  • apt
  • an init system
  • a suitable kernel package

and here's what's notably absent, pay attention bestie: a bootloader and a partition table. none. zero. not there 🙈

So like, in order to actually boot one of these images, you're supposed to extract the kernel and initrd from the image and pass it to a suitable bootloader. that's the move.

Also: no user account is created and root can login without specifying a password. yeah. it's giving open door policy. it's a test VM, she's built different 💀

⭐ OPTIONS ⭐

  • -h hostname, --hostname=hostname — sets the hostname of the virtual machine. default is testvm. cute name, keep it.
  • --initsystem=systemd | busybox | finit | runit | sysv | none — pick your init system, babe. the default is systemd and that's true independently of the Debian release. And uh — heads up — when you pick none, the resulting image will not be bootable unless something else takes care of creating /sbin/init. no init, no boot, that's just physics 😭 Also, automatic customizations that are specific to a particular init system get skipped when you select a different init system. And when you're using the finit init system, consider passing --include=finit-plugins to mmdebstrap 💫
  • -k sshkey, --sshkey=sshkey — installs the given ssh public key file into the virtual machine image for the root user. this option also causes the ssh server to be installed. by default, no key or server is installed. to connect to the vm, pass a port number to debvm-run with the -s option 🦋
  • -o output, --output=output — the file name of the resulting virtual machine image. default? it gets written to rootfs.ext4. periodt.
  • -r release, --release=release — use the given Debian release. default is unstable (living on the edge, love that for you 🔥). if you pass a complete sources.list that includes release names to mmdebstrap, you may pass an empty string here.
  • -s task, --skip=task — skips a particular task or feature. you can specify this option multiple times, or list multiple tasks to skip by separating them with a comma. by default, no tasks are skipped. here's the full menu of skippable things, bestie:
    • autologin — do not setup the machine for automatic password-less root login on the console. this comprises the following changes that would normally be performed: Automatic root login is configured for the init systems finit, runit, systemd and sysv. Forwarding of the TERM kernel command line to agetty is configured. The root password is deleted such that a login does not ask for it and the system directly boots to a shell prompt.
    • ext4 — normally, mmdebstrap bootstraps to a temporary directory and we create the output ext4 image from that directory. this option causes the creation of the ext4 image to be skipped and the output file becomes a tar archive of the temporary directory instead. Such a tar archive is not suitable for being booted by debvm-run. noted 💀
    • ifupdown — skips installing ifupdown configuration to automatically configure wired interfaces. this is specific to using finit, runit or sysv as init system.
    • initsystem — skips installing an init system. this is equivalent to specifying --initsystem=none.
    • kernel — skips installing a linux kernel image. this can be useful to install a kernel without a package. and btw, if a kernel is installed via the mmdebstrap option --include, automatic kernel installation is automatically skipped anyway.
    • packagelists — reduces the package lists inside the image. The available database for dpkg is not created. The package lists used by apt are deleted. This generally produces a smaller image, but you need to run apt update before installing packages and dpkg --set-selections does not work. trade-offs, babes.
    • systemdnetwork — skips installing libnss-resolve as well as automatic network configuration via systemd-networkd. this is specific to using systemd as init system.
    • usrmerge — by default debvm adds a hook to enable merged-/usr without the usrmerge package given a sufficiently recent Debian release. without the hook, dependencies will pull the usrmerge package as needed, which may result in a larger installation.
  • -z size, --size=size — the minimum image size, as an integer plus an optional unit (example: 10K is 10*1024). units are K,M,G,T (powers of 1024). the resulting image will be grown as a sparse file to this size if necessary. default is 2 GB ✨
  • -- mmdebstrap options — everything beyond a double dash gets passed to mmdebstrap after the suite and target specification. you can use this to provide additional hooks for image customization. you can also request additional packages to be installed into the image using mmdebstrap's --include option. Any positional arguments passed here will be treated as mirror specifications by mmdebstrap. And in particular — you can also change the architecture of the resulting image using the --architecture option. 💫

🌈 EXAMPLES 🌈

okay this is the fun part, let's get into it 🎀

When creating an image with multiple architectures, the kernel selection will prefer the sibling 64bit architecture.

debvm-create ... -- --architecture=armhf,arm64

In order to create images for Debian ports architectures, you can pass two options to mmdebstrap.

debvm-create ... -- http://deb.debian.org/debian-ports --keyring=/usr/share/keyrings/debian-ports-archive-keyring.gpg

You can also install a graphical desktop environment 👑

debvm-create ... -- --hook-dir=/usr/share/mmdebstrap/hooks/useradd --aptopt='Apt::Install-Recommends "true"' --include=linux-image-generic,task-gnome-desktop

Here the hook creates a password-less user user. In order for task-gnome-desktop to work reasonably well, Recommends should be enabled. By default a -cloud kernel that lacks graphics drivers is installed. (so like, enable Recommends or your desktop experience is gonna be a lil sad, fr fr)

Installing Ubuntu is also supported somewhat 🦋

debvm-create --release kinetic -- --keyring=/usr/share/keyrings/ubuntu-archive-keyring.gpg --components=main,universe --include=e2fsprogs

Note that universe must be enabled as the merged-usr and systemdnetwork hooks rely packages from that component. e2fsprogs should be pulled by initramfs-tools. iykyk

There also is an aid for sharing a directory with the VM 💖

debvm-create ... -- --include=linux-image-generic --hook-dir=/usr/share/mmdebstrap/hooks/9pmount
debvm-run ... -- -virtfs local,security_model=none,path=/host_path,mount_tag=guest_tag

This will mount the directory /host_path from the host as /media/guest_tag in the VM during boot using 9P. Note that the -cloud kernel lacks the 9P filesystem driver. so like, pick your kernel accordingly bestie 😭

💜 SEE ALSO 💜

and that's the whole page, bestie! go forth and build your little test VMs, you're gonna eat 💅

this lil writeup is from perl v5.40.1, dated 2026-03-23 🎀 mwah, bye!

📦 where this page comes from