quickemu/docs/quickemu_conf.1

.\" Automatically generated by Pandoc 2.19.2
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "QUICKEMU_CONF" "1" "April 30, 2023" "quickemu_conf" "Quickemu Configuration Manual"
.hy
.SH NAME
.PP
quickemu_conf - Options and parameters in the quickemu <vm>.conf
.SH DESCRIPTION
.PP
\f[B]quickemu\f[R] will create and run highly optimised desktop virtual
machines for Linux, macOS and Windows.
It uses sensible defaults, but many configuration options can be
overridden in the required configuration file, which will as a minimum
specify the path to the installation ISO and QEMU disk for the installed
VM
.SH OPTIONS
.PP
These are the options and defaults for the <vm>.conf file
.IP
.nf
\f[C]
# Lowercase variables are used in the VM config file only
boot=\[dq]efi\[dq]
cpu_cores=\[dq]\[dq]
disk_img=\[dq]\[dq]
disk_size=\[dq]\[dq]
display=\[dq]\[dq]
extra_args=\[dq]\[dq]
fixed_iso=\[dq]\[dq]
floppy=\[dq]\[dq]
guest_os=\[dq]linux\[dq]
img=\[dq]\[dq]
iso=\[dq]\[dq]
macaddr=\[dq]\[dq]
macos_release=\[dq]\[dq]
network=\[dq]\[dq]
port_forwards=()
preallocation=\[dq]off\[dq]
ram=\[dq]\[dq]
secureboot=\[dq]off\[dq]
tpm=\[dq]off\[dq]
usb_devices=()
viewer=\[dq]spicy\[dq]
ssh_port=\[dq]\[dq]
spice_port=\[dq]\[dq]
public_dir=\[dq]\[dq]
monitor=\[dq]socket\[dq]
monitor_telnet_port=\[dq]4440\[dq]
monitor_telnet_host=\[dq]localhost\[dq]
monitor_cmd=\[dq]\[dq]
serial=\[dq]socket\[dq]
serial_telnet_port=\[dq]6660\[dq]
serial_telnet_host=\[dq]localhost\[dq]
# options: ehci(USB2.0), xhci(USB3.0)
usb_controller=\[dq]ehci\[dq]
# options: ps2, usb, virtio
keyboard=\[dq]usb\[dq]
keyboard_layout=\[dq]en-us\[dq]
# options: ps2, usb, tablet, virtio
mouse=\[dq]tablet\[dq]
\f[R]
.fi
.SH EXAMPLES
.IP
.nf
\f[C]
guest_os=\[dq]linux\[dq]
disk_img=\[dq]debian-bullseye/disk.qcow2\[dq]
iso=\[dq]debian-bullseye/firmware-11.0.0-amd64-DVD-1.iso\[dq]
\f[R]
.fi
.PP
The default macOS configuration looks like this:
.IP
.nf
\f[C]
guest_os=\[dq]macos\[dq]
img=\[dq]macos-catalina/RecoveryImage.img\[dq]
disk_img=\[dq]macos-catalina/disk.qcow2\[dq]
macos_release=\[dq]catalina\[dq]
\f[R]
.fi
.IP \[bu] 2
\f[V]guest_os=\[dq]macos\[dq]\f[R] instructs Quickemu to optimise for
macOS.
.IP \[bu] 2
\f[V]macos_release=\[dq]catalina\[dq]\f[R] instructs Quickemu to
optimise for a particular macOS release.
.RS 2
.IP \[bu] 2
For example VirtIO Network and Memory Ballooning are available in Big
Sur and newer, but not previous releases.
.IP \[bu] 2
And VirtIO Block Media (disks) are supported/stable in Catalina and
newer.
.RE
.PP
The default Windows 11 configuration looks like this:
.IP
.nf
\f[C]
guest_os=\[dq]windows\[dq]
disk_img=\[dq]windows-11/disk.qcow2\[dq]
iso=\[dq]windows-11/Win11_EnglishInternational_x64.iso\[dq]
fixed_iso=\[dq]windows-11/virtio-win.iso\[dq]
tpm=\[dq]on\[dq]
secureboot=\[dq]on\[dq]
\f[R]
.fi
.IP \[bu] 2
\f[V]guest_os=\[dq]windows\[dq]\f[R] instructs \f[V]quickemu\f[R] to
optimise for Windows.
.IP \[bu] 2
\f[V]fixed_iso=\f[R] specifies the ISO image that provides VirtIO
drivers.
.IP \[bu] 2
\f[V]tpm=\[dq]on\[dq]\f[R] instructs \f[V]quickemu\f[R] to create a
software emulated TPM device using \f[V]swtpm\f[R].
.SH BIOS and EFI
.PP
Since Quickemu 2.1.0 \f[V]efi\f[R] is the default boot option.
If you want to override this behaviour then add the following line to
you VM configuration to enable legacy BIOS.
.IP \[bu] 2
\f[V]boot=\[dq]legacy\[dq]\f[R] - Enable Legacy BIOS boot
.SH Tuning CPU cores, RAM & disks
.PP
By default, Quickemu will calculate the number of CPUs cores and RAM to
allocate to a VM based on the specifications of your host computer.
You can override this default behaviour and tune the VM configuration to
your liking.
.PP
Add additional lines to your virtual machine configuration:
.IP \[bu] 2
\f[V]cpu_cores=\[dq]4\[dq]\f[R] - Specify the number of CPU cores
allocated to the VM
.IP \[bu] 2
\f[V]ram=\[dq]4G\[dq]\f[R] - Specify the amount of RAM to allocate to
the VM
.IP \[bu] 2
\f[V]disk_size=\[dq]16G\[dq]\f[R] - Specify the size of the virtual disk
allocated to the VM
.SS Disk preallocation
.PP
Preallocation mode (allowed values: \f[V]off\f[R] (default),
\f[V]metadata\f[R], \f[V]falloc\f[R], \f[V]full\f[R]).
An image with preallocated metadata is initially larger but can improve
performance when the image needs to grow.
.PP
Specify what disk preallocation should be used, if any, when creating
the system disk image by adding a line like this to your VM
configuration.
.IP \[bu] 2
\f[V]preallocation=\[dq]metadata\[dq]\f[R]
.SS CD-ROM disks
.PP
If you want to expose an ISO image from the host to guest add the
following line to the VM configuration:
.IP \[bu] 2
\f[V]fixed_iso=\[dq]/path/to/image.iso\[dq]\f[R]
.SS Floppy disks
.PP
If you\[cq]re like Alan Pope (https://popey.com) you\[cq]ll probably
want to mount a floppy disk image in the guest.
To do so add the following line to the VM configuration:
.IP \[bu] 2
\f[V]floppy=\[dq]/path/to/floppy.img\[dq]\f[R]
.SH File Sharing
.PP
All File Sharing options will only expose \f[V]\[ti]/Public\f[R] (or
localised variations) for the current user to the guest VMs.
.SS Samba \[u1F427] \[u1F34F] \[u1FA9F]
.PP
If \f[V]smbd\f[R] is available on the host, Quickemu will automatically
enable the built-in QEMU support for exposing a Samba share from the
host to the guest.
.PP
You can install the minimal Samba components on Ubuntu using:
.IP
.nf
\f[C]
sudo apt install --no-install-recommends samba
\f[R]
.fi
.PP
If everything is set up correctly, the \f[V]smbd\f[R] address will be
printed when the virtual machine is started.
For example:
.IP
.nf
\f[C]
 - smbd:     On guest: smb://10.0.2.4/qemu
\f[R]
.fi
.PP
If using a Windows guest, right-click on \[lq]This PC\[rq], click
\[lq]Add a network location\[rq], and paste this address, removing
\f[V]smb:\f[R] and replacing forward slashes with backslashes (in this
example \f[V]\[rs]\[rs]10.0.2.4\[rs]qemu\f[R]).
.SS SPICE WebDAV \[u1F427] \[u1FA9F]
.IP \[bu] 2
TBD
.SS VirtIO-9P \[u1F427] \[u1F34F]
.IP \[bu] 2
TBD
.SH Network port forwarding
.PP
Add an additional line to your virtual machine configuration.
For example:
.IP \[bu] 2
\f[V]port_forwards=(\[dq]8123:8123\[dq] \[dq]8888:80\[dq])\f[R]
.PP
In the example above:
.IP \[bu] 2
Port 8123 on the host is forwarded to port 8123 on the guest.
.IP \[bu] 2
Port 8888 on the host is forwarded to port 80 on the guest.
.SH Disable networking
.PP
To completely disable all network interfaces in a guest VM add this
additional line to your virtual machine configuration:
.IP \[bu] 2
\f[V]network=\[dq]none\[dq]\f[R]
.SH Restricted networking
.PP
You can isolate the guest from the host (and broader network) using the
restrict option, which will restrict networking to just the guest and
any virtual devices.
.PP
This can be used to prevent software running inside the guest from
phoning home while still providing a network inside the guest.
Add this additional line to your virtual machine configuration:
.IP \[bu] 2
\f[V]network=\[dq]restrict\[dq]\f[R]
.SH Bridged networking
.PP
Connect your virtual machine to a preconfigured network bridge.
Add an additional line to your virtual machine configuration:
.IP \[bu] 2
\f[V]network=\[dq]br0\[dq]\f[R]
.PP
If you want to have a persistent MAC address for your bridged network
interface in the guest VM you can add \f[V]macaddr\f[R] to the virtual
machine configuration.
QEMU requires that the MAC address is in the range:
\f[B]52:54:00:AB:00:00 - 52:54:00:AB:FF:FF\f[R]
.PP
So you can generate your own MAC addresses with:
.IP \[bu] 2
\f[V]macaddr=\[dq]52:54:00:AB:51:AE\[dq]\f[R]
.SH USB redirection
.PP
Quickemu supports USB redirection via SPICE pass-through and host
pass-through.
.SS SPICE redirection (recommended)
.PP
Using SPICE for USB pass-through is easiest as it doesn\[cq]t require
any elevated permission, start Quickemu with \f[V]--display spice\f[R]
and then select \f[V]Input\f[R] ->
\f[V]Select USB Device for redirection\f[R] from the menu to choose
which device(s) you want to attach to the guest.
.SS Host redirection \f[B]NOT Recommended\f[R]
.PP
\f[B]USB host redirection is not recommended\f[R], it is provided purely
for backwards compatibility to older versions of Quickemu.
Using SPICE is preferred, see above.
.PP
Add an additional line to your virtual machine configuration.
For example:
.IP \[bu] 2
\f[V]usb_devices=(\[dq]046d:082d\[dq] \[dq]046d:085e\[dq])\f[R]
.PP
In the example above:
.IP \[bu] 2
The USB device with vendor_id 046d and product_id 082d will be exposed
to the guest.
.IP \[bu] 2
The USB device with vendor_id 046d and product_id 085e will be exposed
to the guest.
.PP
If the USB devices are not writable, \f[V]quickemu\f[R] will display the
appropriate commands to modify the USB device(s) access permissions,
like this:
.IP
.nf
\f[C]
 - USB:      Host pass-through requested:
              - Sennheiser Communications EPOS GTW 270 on bus 001 device 005 needs permission changes:
                sudo chown -v root:user /dev/bus/usb/001/005
                ERROR! USB permission changes are required \[u1F446]
\f[R]
.fi
.SH TPM
.PP
Since Quickemu 2.2.0 a software emulated TPM device can be added to
guest virtual machines.
Just add \f[V]tpm=\[dq]on\[dq]\f[R] to your VM configuration.
\f[V]quickget\f[R] will automatically add this line to Windows 11
virtual machines.
.SH AUTHORS
.PP
Written by Martin Wimpress.
.SH BUGS
.PP
Submit bug reports online at:
<https://github.com/quickemu-project/quickemu/issues>
.SH SEE ALSO
.PP
Full sources at: <https://github.com/quickemu-project/quickemu>
.PP
quickget(1), quickemu(1), quickgui(1)
.SH AUTHORS
Martin Wimpress.