Ubuntu Manpage: debvm-run - 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.

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

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.

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