DEBVM-RUN(1)

💖 DEBVM-RUN 💖 (that's the debvm-run(1) manual page, bestie)

okay so. picture this. you made a whole VM image and now you wanna, like, run it? yeah. that's this. no cap.

---

✨ NAME ✨

debvm-run — run a VM image that was made by debvm-create 🫶

---

🌸 SYNOPSIS 🌸

debvm-run [-g] [-i image] [-s sshport] [-- qemu options]

---

🦋 DESCRIPTION 🦋

so debvm-run is basically a thin little wrapper around qemu — like, it's giving "qemu but make it convenient" — and what it does is run a virtual machine image that came from debvm-create, or honestly anything compatible with it. 💅

the image it expects? a raw ext4 image, and it needs a non-empty file system label. like, don't come in here with a blank label, that's not the vibe.

the architecture of the machine gets detected from the /bin/true inside the image. yep. that's the whole trick. it's giving forensic girlie.

it also has to contain a symbolic link pointing to a kernel image at one of (|/boot)/vmlinu[xz], plus a symbolic link pointing to an initrd image at initrd.img in the same directory as the kernel image. both of those get extracted and handed over to qemu. 🌈

and then — automatic — a net interface configured for user mode gets added. no extra steps, it's just there. iconic.

---

💅 OPTIONS 💅

• --append=cmdline — okay so yes, you could just pass -append straight to qemu, but bestie, that replaces the entire command line and nukes all the important values debvm-run passed in. rude. this option instead appends your command line arguments onto the automatic ones. and if you use it more than once, that's also appending, not replacing. 🎀
• -g, --graphical — by default -nographic gets passed to qemu and you vibe with the machine's serial console. this option skips that whole configuration. ⚠️ note though: debvm-create defaults to installing a cloud kernel if one's available, so you might have to pass --include=linux-image-generic during image construction to actually get graphics drivers. plan accordingly, queen.
• -i image, --image=image — tells it where the virtual machine image file lives. default? rootfs.ext4 in the working directory. periodt.
• --netopt=option — debvm-run sets up a user mode network by default, which means it passes a -netdev option to qemu. this option lets you customize the value of that -netdev option. for example, you can set up extra port forwards like "--netopt hostfwd=:127.0.0.1:8080-:80". it can be used multiple times. 🔥
• --skip=task — skips a particular task or feature. you can specify it multiple times, or list multiple tasks separated by a comma. by default, no tasks are skipped. here's what you can skip:
  • network — don't configure a network card. use this if you wanna set up networking yourself. and heads up, you should also pass -nic none along with this when you actually want to disable networking entirely.
  • rngdev — don't pass a random number generator device.
  • root — skips all the tasks matching root/*. ⚠️ and if either of those is present, the VM will not boot unless you add a suitable replacement some other way. like, actually won't boot. so don't be cute about it.
  • root/cmd — since debvm-run uses qemu as the bootloader, it normally passes the label of the root block device via the kernel command line. this passing can be inhibited so you can supply a different location.
  • root/dev — a block device for the root filesystem is no longer passed. use this to customize the block device.
• --transport=transport — when debvm adds devices to qemu, it has to pick a transport, and most of the time it guesses pci. if you specify a different machine like -machine microvm, you might need a different transport like device. 👑
• -s sshport, --sshport=sshport — if you give it, qemu gets configured to pass connections to 127.0.0.1:sshport through to port 22 of the virtual machine. and you can connect to your VM without updating your known hosts, like this:

ssh -o NoHostAuthenticationForLocalhost=yes -p $sshport root@127.0.0.1

it's a shorthand for "--netopt hostfwd=tcp:127.0.0.1:sshport-:22". ✨

• -- qemu options — everything past a double dash gets passed to qemu. use this to configure extra hardware components. one possible use? passing -snapshot to avoid modifying the virtual machine image. chef's kiss.

---

🌟 EXAMPLES 🌟

run a virtual machine stored in the image rootfs.ext4 (the default, bestie) with local port 8022 routed to port 22 of the virtual machine. the -snapshot argument gets passed to QEMU and prevents any permanent changes to rootfs.ext4, which means you get an ephemeral run. 🧚

debvm-run -s 8022 -i rootfs.ext4 -- -snapshot

---

🎀 FAQ 🎀

the debvm-run console renders wrong.

make sure $TERM is set to a value known inside the VM. you may need to install ncurses-term for more definitions. also the serial console will miss events of resizing the terminal emulator — in that case you may run "setterm --resize". 😭

how can I kill debvm-run?

the wrapped qemu can be terminated by pressing Ctrl-a x. refer to the qemu manual page for more escape sequences. iykyk. 💀

---

💜 LIMITATIONS 💜

so, because of the way the kernel and bootloader get extracted before running qemu, you can't upgrade a kernel and then just reboot. if you try that, it'll still use the old kernel. instead, qemu must be terminated and debvm-run should be launched again to pick up the new kernel. and to avoid accidental reboots, you may pass -no-reboot to qemu. noted. 🙈

for 32bit arm, highmem is actively disabled, because the default kernel flavour fails to boot. if you want to pass more ram, please also pass -machine virt and install a lpae kernel. alternatively, use an arm64 kernel. slay. 🌸

---

⭐ SEE ALSO ⭐

debvm-create(1) qemu(1)

---

and that's the whole page, bestie — this was perl v5.40.1, dated 2026-03-23, and it's the DEBVM-RUN(1) manual, so go forth and virtualize responsibly. mwah. 💖✨🎀