340 lines
11 KiB
Groff
340 lines
11 KiB
Groff
.\" Automatically generated by Pandoc 3.2
|
|
.\"
|
|
.TH "QUICKEMU_CONF" "1" "June 24, 2024" "quickemu_conf" "Quickemu Configuration Manual"
|
|
.SH NAME
|
|
quickemu_conf \- Options and parameters in the quickemu <vm>.conf
|
|
.SH DESCRIPTION
|
|
\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
|
|
These are the options and defaults for the <vm>.conf file
|
|
.IP
|
|
.EX
|
|
# 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]
|
|
.EE
|
|
.SH EXAMPLES
|
|
.IP
|
|
.EX
|
|
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]
|
|
.EE
|
|
.PP
|
|
The default macOS configuration looks like this:
|
|
.IP
|
|
.EX
|
|
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]
|
|
.EE
|
|
.IP \[bu] 2
|
|
\f[CR]guest_os=\[dq]macos\[dq]\f[R] instructs Quickemu to optimise for
|
|
macOS.
|
|
.IP \[bu] 2
|
|
\f[CR]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
|
|
.EX
|
|
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]
|
|
.EE
|
|
.IP \[bu] 2
|
|
\f[CR]guest_os=\[dq]windows\[dq]\f[R] instructs \f[CR]quickemu\f[R] to
|
|
optimise for Windows.
|
|
.IP \[bu] 2
|
|
\f[CR]fixed_iso=\f[R] specifies the ISO image that provides VirtIO
|
|
drivers.
|
|
.IP \[bu] 2
|
|
\f[CR]tpm=\[dq]on\[dq]\f[R] instructs \f[CR]quickemu\f[R] to create a
|
|
software emulated TPM device using \f[CR]swtpm\f[R].
|
|
.SS BIOS and EFI
|
|
Since Quickemu 2.1.0 \f[CR]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[CR]boot=\[dq]legacy\[dq]\f[R] \- Enable Legacy BIOS boot
|
|
.SS Tuning CPU cores, RAM & disks
|
|
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[CR]cpu_cores=\[dq]4\[dq]\f[R] \- Specify the number of CPU cores
|
|
allocated to the VM
|
|
.IP \[bu] 2
|
|
\f[CR]ram=\[dq]4G\[dq]\f[R] \- Specify the amount of RAM to allocate to
|
|
the VM
|
|
.IP \[bu] 2
|
|
\f[CR]disk_size=\[dq]16G\[dq]\f[R] \- Specify the size of the virtual
|
|
disk allocated to the VM
|
|
.SS Disk preallocation
|
|
Preallocation mode (allowed values: \f[CR]off\f[R] (default),
|
|
\f[CR]metadata\f[R], \f[CR]falloc\f[R], \f[CR]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[CR]preallocation=\[dq]metadata\[dq]\f[R]
|
|
.SS CD\-ROM disks
|
|
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[CR]fixed_iso=\[dq]/path/to/image.iso\[dq]\f[R]
|
|
.SS Floppy disks
|
|
If you\[aq]re like \c
|
|
.UR https://popey.com
|
|
Alan Pope
|
|
.UE \c
|
|
\ you\[aq]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[CR]floppy=\[dq]/path/to/floppy.img\[dq]\f[R]
|
|
.SS File Sharing
|
|
All File Sharing options will only expose \f[CR]\[ti]/Public\f[R] (or
|
|
localised variations) for the current user to the guest VMs.
|
|
.SS Samba 🐧 🍏 🪟
|
|
If \f[CR]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
|
|
.EX
|
|
sudo apt install \-\-no\-install\-recommends samba
|
|
.EE
|
|
.PP
|
|
If everything is set up correctly, the \f[CR]smbd\f[R] address will be
|
|
printed when the virtual machine is started.
|
|
For example:
|
|
.IP
|
|
.EX
|
|
\- smbd: On guest: smb://10.0.2.4/qemu
|
|
.EE
|
|
.PP
|
|
If using a Windows guest, right\-click on \[dq]This PC\[dq], click
|
|
\[dq]Add a network location\[dq], and paste this address, removing
|
|
\f[CR]smb:\f[R] and replacing forward slashes with backslashes (in this
|
|
example \f[CR]\[rs]\[rs]10.0.2.4\[rs]qemu\f[R]).
|
|
.SS SPICE WebDAV 🐧 🪟
|
|
.IP \[bu] 2
|
|
TBD
|
|
.SS VirtIO\-9P 🐧 🍏
|
|
.IP \[bu] 2
|
|
TBD
|
|
.SS Networking
|
|
.SS Port forwarding
|
|
Add an additional line to your virtual machine configuration.
|
|
For example:
|
|
.IP \[bu] 2
|
|
\f[CR]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.
|
|
.SS Disable networking
|
|
To completely disable all network interfaces in a guest VM add this
|
|
additional line to your virtual machine configuration:
|
|
.IP \[bu] 2
|
|
\f[CR]network=\[dq]none\[dq]\f[R]
|
|
.SS Restricted networking
|
|
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[CR]network=\[dq]restrict\[dq]\f[R]
|
|
.SS Bridged networking
|
|
Connect your virtual machine to a preconfigured network bridge.
|
|
Add an additional line to your virtual machine configuration:
|
|
.IP \[bu] 2
|
|
\f[CR]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[CR]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[CR]macaddr=\[dq]52:54:00:AB:51:AE\[dq]\f[R]
|
|
.SS USB redirection
|
|
Quickemu supports USB redirection via SPICE pass\-through and host
|
|
pass\-through.
|
|
Quickemu supports USB redirection via SPICE pass\-through and host
|
|
pass\-through.
|
|
.PP
|
|
\f[B]NOTE!\f[R] When a USB device is redirected from the host, it will
|
|
not be usable by host operating system until the guest redirection is
|
|
stopped.
|
|
Therefore, do not redirect the input devices, such as the keyboard and
|
|
mouse, as it will be difficult (or impossible) to revert the situation.
|
|
.SS SPICE redirection (recommended)
|
|
Using SPICE for USB pass\-through is easiest as it doesn\[aq]t require
|
|
any elevated permission:
|
|
.PP
|
|
Both \f[CR]spicy\f[R] from \c
|
|
.UR https://www.spice-space.org/spice-gtk.html
|
|
spice\-gtk
|
|
.UE \c
|
|
\ (\f[I]Input \-> Select USB Devices for redirection\f[R]) and
|
|
\f[CR]remote\-viewer\f[R] from \c
|
|
.UR https://gitlab.com/virt-viewer/virt-viewer
|
|
virt\-viewer
|
|
.UE \c
|
|
\ (\f[I]File \-> USB device selection\f[R]) support this feature.
|
|
.IP \[bu] 2
|
|
Start Quickemu with \f[CR]\-\-display spice\f[R] and then
|
|
.IP \[bu] 2
|
|
Select \f[CR]Input\f[R] \-> \f[CR]Select USB Device for redirection\f[R]
|
|
from the menu to choose which device(s) you want to attach to the guest.
|
|
.IP \[bu] 2
|
|
**\f[CR]spicy\f[R] (default)
|
|
.RS 2
|
|
.IP \[bu] 2
|
|
**Select \f[CR]Input\f[R] \->
|
|
\f[CR]Select USB Device for redirection\f[R] from the menu to choose
|
|
which device(s) you want to attach to the guest.
|
|
.RE
|
|
.IP \[bu] 2
|
|
**\f[CR]remote\-viewer\f[R]
|
|
.RS 2
|
|
.IP \[bu] 2
|
|
**Select \f[CR]File\f[R] \-> \f[CR]USB device selection\f[R] from the
|
|
menu to choose which device(s) you want to attach to the guest.
|
|
.RE
|
|
.PP
|
|
To ensure that this functionality works as expected, make sure that you
|
|
have installed the necessary SPICE Guest Tools on the virtual machine.
|
|
.SS Enabling SPICE redirection on NixOS
|
|
On NixOS, if you encounter this error:
|
|
.IP
|
|
.EX
|
|
Error setting facl: Operation not permitted
|
|
.EE
|
|
.PP
|
|
Try setting \c
|
|
.UR https://search.nixos.org/options?channel=23.11&show=virtualisation.spiceUSBRedirection.enable&from=0&size=50&sort=relevance&type=packages&query=spiceusbredirec
|
|
the following option
|
|
.UE \c
|
|
:
|
|
.IP
|
|
.EX
|
|
virtualisation.spiceUSBRedirection.enable = true;
|
|
.EE
|
|
.SS Host redirection (\f[B]NOT Recommended\f[R])
|
|
\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[CR]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[CR]quickemu\f[R] will display
|
|
the appropriate commands to modify the USB device(s) access permissions,
|
|
like this:
|
|
.IP
|
|
.EX
|
|
\- 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 👆
|
|
.EE
|
|
.SS TPM
|
|
Since Quickemu 2.2.0 a software emulated TPM device can be added to
|
|
guest virtual machines.
|
|
Just add \f[CR]tpm=\[dq]on\[dq]\f[R] to your VM configuration.
|
|
\f[CR]quickget\f[R] will automatically add this line to Windows 11
|
|
virtual machines.
|
|
.SH AUTHORS
|
|
Written by Martin Wimpress.
|
|
.SH BUGS
|
|
Submit bug reports online at: \c
|
|
.UR https://github.com/quickemu-project/quickemu/issues
|
|
.UE \c
|
|
.SH SEE ALSO
|
|
Full sources at: \c
|
|
.UR https://github.com/quickemu-project/quickemu
|
|
.UE \c
|
|
.PP
|
|
quickget(1), quickemu(1), quickgui(1)
|
|
.SH AUTHORS
|
|
Martin Wimpress.
|