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 pass configure network card.

               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.

SEE ALSO

           debvm-create(1) qemu(1)