Scroll to navigation

DEBVM-CREATE(1) User Contributed Perl Documentation DEBVM-CREATE(1)

NAME

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

SYNOPSIS

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

DESCRIPTION

debvm-create is essentially a thin wrapper around mmdebstrap for creating a raw ext4 filesystem image for booting with debvm-run. The purpose of these images primarily is testing the different releases and architectures without access to a physical machine of that architecture. Beyond essential packages, the image will contain apt, an init system and a suitable kernel package. Notably absent is a bootloader and a partition table. In order to boot such an image, one is supposed to extract the kernel and initrd from the image and pass it to a suitable bootloader. No user account is created and root can login without specifying a password.

OPTIONS

Specify a Debian architecture name. Its semantics are compatible with the --architecture option of mmdebstrap and its value is forwarded to mmdebstrap. It can be passed as a mmdebstrap option or as a debvm option. If given as a debvm option, architecture-specific quirks can be applied (e.g. for Hurd). By default, the native architecture is being used.
Set the hostname of the virtual machine. By default, the hostname is testvm.
Select an init system to be used. The default is systemd independently of the Debian release. Note that when selecting none, the resulting image will not be bootable unless something else takes care of creating /sbin/init. Automatic customizations that are specific to a particular init system will be skipped when a different init system is selected. When using the finit init system consider passing --include=finit-plugins to mmdebstrap.
Install 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.
Specify the file name of the resulting virtual machine image. By default, it is written to rootfs.ext4.
Use the given Debian release. By default, unstable is being used. If you pass a complete sources.list that includes release names to mmdebstrap, you may pass an empty string here.
Skip a particular task or feature. The option may be specified multiple times or list multiple tasks to be skipped by separating them with a comma. By default, no tasks are skipped. The following tasks may be skipped.
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, openrc, 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.
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.
skips installing ifupdown configuration to automatically configure wired interfaces. This is specific to using finit, runit, openrc or sysv as init system.
skips installing an init system. This is equivalent to specifying --initsystem=none.
skips installing a linux kernel image. This can be useful to install a kernel without a package. If a kernel is installed via mmdebstrap option "--include", automatic kernel installation is automatically skipped.
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.
skips installing libnss-resolve as well as automatic network configuration via systemd-networkd. This is specific to using systemd as init system.
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.
Specify the minimum image size as an integer and 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. The default is 2 GB.
All options beyond a double dash are passed to mmdebstrap after the suite and target specification. This can be used 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. In particular, you can also change the architecture of the resulting image using the --architecture option.

EXAMPLES

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

For GNU/Hurd you have to use chrootless mode and add the unreleased suite. CAUTION: using chrootless mode runs package maintainer scripts without chroot isolation which may have unintended consequences for the system running debvm-create. It is strongly advised to run debvm-create inside a chroot but at least run it as an unprivileged user:

    mmdebstrap --unshare-helper debvm-create --output /tmp/rootfs.ext4 --architecture=hurd-i386 -- --mode=chrootless --include=debian-ports-archive-keyring "deb http://ftp.ports.debian.org/debian-ports/ unstable main" "deb http://ftp.ports.debian.org/debian-ports/ unreleased main"
    unshare --map-auto --map-root-user chown root:root /tmp/rootfs.ext4
    debvm-run -i /tmp/rootfs.ext4

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.

You can create bit-by-bit reproducible debvm images from a given snapshot.d.o timestamp.

    SOURCE_DATE_EPOCH=1612543740 debvm-create ... -- \
        --aptopt='Acquire::Check-Valid-Until "false"' \
        --aptopt='APT::Snapshot "20210205T164900Z"'

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

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.

LIMITATIONS

The output format is fixed as a sparse raw file containing an ext4 filesystem image. This format is tightly tied to the current implementation of debvm-run. In particular, it cannot yet consume qcow2 images. Therefore, debvm-create cannot create qcow2 images. If a qcow2 image is desired, you can convert it afterwards.

    qemu-img convert -f raw -O qcow2 rootfs.ext4 rootfs.qcow2

Note that creating the image in-place as qcow2 is not supported by underlying tools.

SEE ALSO

    debvm-run(1) mmdebstrap(1)
2026-10-01 perl v5.42.3