---
name: "debvm-run"
section: "1"
platform: "linux"
package: "debvm"
version: "0.4.5+deb13u1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/debvm-run"
---

# debvm-run(1)

Run a VM image created by debvm-create

## NAME

debvm-run - Run a VM image created by debvm-create

## SYNOPSIS

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

## DESCRIPTION

**debvm-run** is essentially a thin wrapper around **qemu** for running a virtual machine image created by **debvm-create** or something compatible. The virtual machine image is expected to be a raw ext4 image with a non-empty file system label. The architecture of the machine is detected from the contained */bin/true*. It must contain a symbolic link pointing to a kernel image at one of *(\|/boot)/vmlinu\[xz\]* a symbolic link pointing to an initrd image at *initrd.img* in the same directory as the kernel image. Both are extracted and passed to **qemu**. A net interface configured for user mode is added automatically.

## OPTIONS

- **--append**=*cmdline*

  While the kernel command line can be modified by passing **-append** to **qemu** directly, doing that always replaces the entire command line and thus removes important values passed by **debvm-run**. This variant instead appends given command line arguments to the automatic ones. Repeated use also causes appending rather than replacement.

- **-g**, **--graphical**

  By default, the option **-nographic** is passed to **qemu** and one interacts with the serial console of the machine. This configuration is skipped in the presence of this option. Note that **debvm-create** defaults to installing a cloud kernel if available, so you may have to pass `"--include=linux-image-generic"` during image construction to get graphics drivers.

- **-i** *image*, **--image**=*image*

  This option specifies the location of the virtual machine image file. By default *rootfs.ext4* in the working directory is used.

- **--netopt**=*option*

  **debvm-run** sets up a user mode network by default. It therefore passes a **-netdev** option to **qemu**. Using this option, you can customize the value of that **-netdev** option. For instance, you can set up additional port forwards by passing e.g. `"--netopt hostfwd=:127.0.0.1:8080-:80"`. It can be used multiple times.

- **--skip**=*task*

  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.

  - **network**

    Do not configure a network card. Use this if you want to configure network on your own. This should also be passed in addition to passing `"-nic none"` when you want to disable networking.

  - **rngdev**

    Do not pass a random number generator device.

  - **root**

    Skip all of the following tasks matching `"root/*"`. If either of these is present, the VM will not boot unless a suitable replacement is added in another way.

  - **root/cmd**

    Since **debvm-run** uses **qemu** as bootloader it normally passes the label of the root block device via the kernel command line. This passing can be inhibited to supply a different location.

  - **root/dev**

    A block device for the root filesystem is no longer passed. This can be used to customize the block device.

- **--transport**=*transport*

  When **debvm** adds devices to **qemu**, it has to select a transport and it most often guesses **pci**. When specifying a different machine such as **-machine microvm**, a different transport such as **device** may be needed.

- **-s** *sshport*, **--sshport**=*sshport*

  If given, **qemu** is configured to pass connections to *127.0.0.1:sshport* to port 22 of the virtual machine. You can connect to your virtual machine without updating your known hosts like this:

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

  The option is a shorthand for `"--netopt hostfwd=tcp:127.0.0.1:sshport-:22"`.

- **--** *qemu options*

  All options beyond a double dash are passed to **qemu**. This can be used to configure additional hardware components. One possible use of this method is passing **-snapshot** to avoid modifying the virtual machine image.

## EXAMPLES

Run a virtual machine stored in the image *rootfs.ext4* (the default) with local port 8022 routed to port 22 of the virtual machine. The **-snapshot** argument is passed to QEMU and prevents any permanent changes to *rootfs.ext4*, resulting in 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. The serial console will miss events of resizing the terminal emulator. You may run `"setterm --resize"` in that case.

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

## LIMITATIONS

Due to the way kernel and bootloader are being extracted before running **qemu**, one cannot upgrade a kernel and then just reboot. Attempting to do so, will still use the old kernel. Instead, **qemu** must be terminated and **debvm-run** should be launched again to pick up the new kernel. In order to avoid accidental reboots, one may pass **-no-reboot** to **qemu**.

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.

## SEE ALSO

```
    debvm-create(1) qemu(1)
```