328 lines
9.5 KiB
Groff
328 lines
9.5 KiB
Groff
.\" 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" "February 3, 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.
|