.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.TH vmexec-run 1  "run " 
.SH NAME
vmexec\-run \- Run a command in a new virtual machine
.SH SYNOPSIS
\fBvmexec run\fR [\fB\-d\fR|\fB\-\-detach\fR] [\fB\-\-rm\fR] [\fB\-\-vmid\fR] [\fB\-\-disable\-kvm\fR] [\fB\-m\fR|\fB\-\-memory\fR] [\fB\-e\fR|\fB\-\-env\fR] [\fB\-w\fR|\fB\-\-workdir\fR] [\fB\-v\fR|\fB\-\-volume\fR] [\fB\-\-pmem\fR] [\fB\-p\fR|\fB\-\-publish\fR] [\fB\-s\fR|\fB\-\-ssh\-timeout\fR] [\fB\-i\fR|\fB\-\-interactive\fR] [\fB\-t\fR|\fB\-\-tty\fR] [\fB\-\-show\-vm\-window\fR] [\fB\-\-pull\fR] [\fB\-h\fR|\fB\-\-help\fR] <\fIIMAGE_SOURCE\fR> [\fIARGS\fR] 
.SH DESCRIPTION
Run a command in a new virtual machine
.SH OPTIONS
.TP
\fB\-d\fR, \fB\-\-detach\fR
Run virtual machine in background and print virtual machine ID
.TP
\fB\-\-rm\fR
Remove virtual machine runtime data after exit
.TP
\fB\-\-vmid\fR \fI<VMID>\fR
Virtual machine identifier

If not provided, a random identifier will be generated.
.TP
\fB\-\-disable\-kvm\fR
Run virtual machine with TCG instead of KVM

This would be mostly useful in environments where KVM is not available. It will be a lot slower but might be acceptable in some contexts.
.TP
\fB\-m\fR, \fB\-\-memory\fR \fI<MEMORY>\fR
Memory limit for the virtual machine in GBs

Must be an integer of at least 1.

If not provided, all available host memory is used.
.TP
\fB\-e\fR, \fB\-\-env\fR \fI<ENV>\fR
Set environment variables for the process inside the virtual machine

Can be provided multiple times.

Expected format: KEY=VALUE
.TP
\fB\-w\fR, \fB\-\-workdir\fR \fI<WORKDIR>\fR
Working directory inside the virtual machine

The default wokring directory for running binaries within a virtual machine is dependent on the image. Most commonly, it\*(Aqll be /root.
.TP
\fB\-v\fR, \fB\-\-volume\fR \fI<VOLUMES>\fR
Bind mount a volume into the virtual machine

Can be provided multiple times.

Expected format: source:dest[:ro]

`ro` can optionally be provided to mark the mount as read\-only.

Example: $PWD/src:/mnt:ro
.TP
\fB\-\-pmem\fR \fI<PMEMS>\fR
Mount a virtio\-pmem device file into the virtual machine

You might want to do this to bypass the guest page cache. This is important if you\*(Aqre overprovisioning your host (i.e. giving VMs more combined memory than the host actually has) and have a write\-heavy workload. For more info, see: https://www.qemu.org/docs/master/system/devices/virtio\-pmem.html

Can be provided multiple times.

Size is in gigabytes.

Expected format: dest:<size>

Example: /var/lib:20
.TP
\fB\-p\fR, \fB\-\-publish\fR \fI<PUBLISHED_PORTS>\fR
Publish a port on the virtual machine to the host

Can be provided multiple times.

Expected format: [[hostip:][hostport]:]vmport

`hostip` is optional and if not provided, the port will be bound on all host IPs.

`hostport` is optional and if not provided, the same value of `vmport` will be used for the host port.

Currently only IPv4 is supported for `hostip`.
.TP
\fB\-s\fR, \fB\-\-ssh\-timeout\fR \fI<SSH_TIMEOUT>\fR [default: 20]
SSH connection timeout

Try for this long (in seconds) to connect to the virtual machine\*(Aqs SSH server.
.TP
\fB\-i\fR, \fB\-\-interactive\fR \fI<INTERACTIVE>\fR [default: auto]
Make STDIN available to the virtual machine\*(Aqs process

If \*(Aqauto\*(Aq, this will try to read from stdin if it is available, and do nothing when stdin is not available. If \*(Aqalways\*(Aq, this will try to read from stdin and abort when stdin is not available.
.br

.br
\fIPossible values:\fR
.RS 14
.IP \(bu 2
always
.IP \(bu 2
never
.IP \(bu 2
auto
.RE
.TP
\fB\-t\fR, \fB\-\-tty\fR \fI<TTY>\fR [default: auto]
Allocate a pseudo\-TTY for the virtual machine

If \*(Aqauto\*(Aq, this will be enabled in case vmexec is run from an interactive terminal.
.br

.br
\fIPossible values:\fR
.RS 14
.IP \(bu 2
always
.IP \(bu 2
never
.IP \(bu 2
auto
.RE
.TP
\fB\-\-show\-vm\-window\fR
Show a window with the virtual machine running in it

This is mostly useful for debugging boot failures.
.TP
\fB\-\-pull\fR \fI<PULL>\fR [default: missing]
When to pull a new image
.br

.br
\fIPossible values:\fR
.RS 14
.IP \(bu 2
missing
.IP \(bu 2
never
.IP \(bu 2
newer
.RE
.TP
\fB\-h\fR, \fB\-\-help\fR
Print help (see a summary with \*(Aq\-h\*(Aq)
.TP
<\fIIMAGE_SOURCE\fR>
Either an operating system (e.g. archlinux) or a path to an image

Possible OS types: archlinux
.TP
[\fIARGS\fR]
Arguments to run in the virtual machine