.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "DEBVM-RUN 1"
.TH DEBVM-RUN 1 "2023-03-21" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
debvm\-run \- Run a VM image created by debvm\-create
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBdebvm-run\fR [\fB\-g\fR] [\fB\-i\fR \fIimage\fR] [\fB\-s\fR \fIsshport\fR] [\fB\-\-\fR \fIqemu options\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBdebvm-run\fR is essentially a thin wrapper around \fBqemu\fR for running a virtual machine image created by \fBdebvm-create\fR 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 \fI/bin/true\fR.
It must contain a symbolic link pointing to a kernel image at one of \fI(|/boot)/vmlinu[xz]\fR a symbolic link pointing to an initrd image at \fIinitrd.img\fR in the same directory as the kernel image.
Both are extracted and passed to \fBqemu\fR.
A net interface configured for user mode is added automatically.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-g\fR, \fB\-\-graphical\fR" 8
.IX Item "-g, --graphical"
By default, the option \fB\-nographic\fR is passed to \fBqemu\fR and one interacts with the serial console of the machine.
This configuration is skipped in the presence of this option.
Note that \fBdebvm-create\fR defaults to installing a cloud kernel if available, so you may have to pass \f(CW\*(C`\-\-include=linux\-image\-generic\*(C'\fR during image construction to get graphics drivers.
.IP "\fB\-i\fR \fIimage\fR, \fB\-\-image\fR=\fIimage\fR" 8
.IX Item "-i image, --image=image"
This option specifies the location of the virtual machine image file.
By default \fIrootfs.ext4\fR in the working directory is used.
.IP "\fB\-s\fR \fIsshport\fR, \fB\-\-sshport\fR=\fIsshport\fR" 8
.IX Item "-s sshport, --sshport=sshport"
If given, \fBqemu\fR is configured to pass connections to \fI127.0.0.1:sshport\fR to port 22 of the virtual machine.
You can connect to your virtual machine without updating your known hosts like this:
.Sp
.Vb 1
\&    ssh \-o NoHostAuthenticationForLocalhost=yes \-p $sshport root@127.0.0.1
.Ve
.IP "\fB\-\-\fR \fIqemu options\fR" 8
.IX Item "-- qemu options"
All options beyond a double dash are passed to \fBqemu\fR.
This can be used to configure additional hardware components.
One possible use of this method is passing \fB\-snapshot\fR to avoid modifying the virtual machine image.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Run a virtual machine stored in the image \fIrootfs.ext4\fR (the default) with
local port 8022 routed to port 22 of the virtual machine. The \fB\-snapshot\fR
argument is passed to \s-1QEMU\s0 and prevents any permanent changes to
\&\fIrootfs.ext4\fR, resulting in an ephemeral run.
.PP
.Vb 1
\&    debvm\-run \-s 8022 \-i rootfs.ext4 \-\- \-snapshot
.Ve
.SH "FAQ"
.IX Header "FAQ"
.IP "The debvm-run console renders wrong." 8
.IX Item "The debvm-run console renders wrong."
Make sure \f(CW$TERM\fR is set to a value known inside the \s-1VM.\s0
You may need to install \fBncurses-term\fR for more definitions.
The serial console will miss events of resizing the terminal emulator.
You may run \f(CW\*(C`setterm \-resize\*(C'\fR in that case.
.IP "How can I kill debvm-run?" 8
.IX Item "How can I kill debvm-run?"
The wrapped \fBqemu\fR can be terminated by pressing Ctrl-a x.
Refer to the \fBqemu\fR manual page for more escape sequences.
.SH "LIMITATIONS"
.IX Header "LIMITATIONS"
Due to the way kernel and bootloader are being extracted before running \fBqemu\fR, one cannot upgrade a kernel and then just reboot.
Attempting to do so, will still use the old kernel.
Instead, \fBqemu\fR must be terminated and \fBdebvm-run\fR should be launched again to pick up the new kernel.
In order to avoid accidental reboots, one may pass \fB\-no\-reboot\fR to \fBqemu\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.Vb 1
\&    debvm\-create(1) qemu(1)
.Ve