762 lines
20 KiB
Groff
762 lines
20 KiB
Groff
|
.\" Automatically generated by Pandoc 2.9.2.1
|
||
|
|
.\"
|
||
|
|
.TH "QUICKEMU" "1" "February 20, 2022" "quickemu" "Quickemu User Manual"
|
||
|
|
.hy
|
||
|
|
.SH NAME
|
||
|
|
.PP
|
||
|
|
quickemu - A quick VM builder and manager
|
||
|
|
.SH SYNOPSIS
|
||
|
|
.PP
|
||
|
|
\f[B]quickemu\f[R] [\f[I]OPTION\f[R]]\&...
|
||
|
|
.SH DESCRIPTION
|
||
|
|
.PP
|
||
|
|
\f[B]quickemu\f[R] will create and run highly optimised desktop virtual
|
||
|
|
machines for Linux, macOS and Windows
|
||
|
|
.SH OPTIONS
|
||
|
|
.TP
|
||
|
|
\f[B]\[en]vm\f[R]
|
||
|
|
vm configuration file
|
||
|
|
.PP
|
||
|
|
You can also pass optional parameters
|
||
|
|
.TP
|
||
|
|
\f[B]\[en]braille\f[R]
|
||
|
|
Enable braille support.
|
||
|
|
Requires SDL.
|
||
|
|
.TP
|
||
|
|
\f[B]\[en]delete\f[R]
|
||
|
|
Delete the disk image.
|
||
|
|
.TP
|
||
|
|
\f[B]\[en]display\f[R]
|
||
|
|
Select display backend.
|
||
|
|
`sdl' (default), `gtk', `none' or `spice'
|
||
|
|
.TP
|
||
|
|
\f[B]\[en]fullscreen\f[R]
|
||
|
|
Starts VM in full screen mode (Ctl+Alt+f to exit)
|
||
|
|
.TP
|
||
|
|
\f[B]\[en]ignore-msrs-always\f[R]
|
||
|
|
Configure KVM to always ignore unhandled machine-specific registers
|
||
|
|
.TP
|
||
|
|
\f[B]\[en]screen <screen>\f[R]
|
||
|
|
Use specified screen to determine the window size.
|
||
|
|
.TP
|
||
|
|
\f[B]\[en]shortcut\f[R]
|
||
|
|
Create a desktop shortcut
|
||
|
|
.TP
|
||
|
|
\f[B]\[en]snapshot apply <tag>\f[R]
|
||
|
|
Apply/restore a snapshot.
|
||
|
|
.TP
|
||
|
|
\f[B]\[en]snapshot create <tag>\f[R]
|
||
|
|
Create a snapshot.
|
||
|
|
.TP
|
||
|
|
\f[B]\[en]snapshot delete <tag>\f[R]
|
||
|
|
Delete a snapshot.
|
||
|
|
.TP
|
||
|
|
\f[B]\[en]snapshot info\f[R]
|
||
|
|
Show disk/snapshot info.
|
||
|
|
.TP
|
||
|
|
\f[B]\[en]status-quo\f[R]
|
||
|
|
Do not commit any changes to disk/snapshot.
|
||
|
|
.TP
|
||
|
|
\f[B]\[en]version\f[R]
|
||
|
|
Print version
|
||
|
|
.SH EXAMPLES
|
||
|
|
.TP
|
||
|
|
\f[B]quickemu \[en]vm ubuntu-mate-21.10-.conf\f[R]
|
||
|
|
Launches the VM specified in the file \f[I]ubuntu-mate-21.10-.conf\f[R]
|
||
|
|
.SS Introduction
|
||
|
|
.PP
|
||
|
|
Quickly create and run highly optimised desktop virtual machines for
|
||
|
|
Linux, macOS and Windows; with just two commands.
|
||
|
|
You decide what operating system you want to run and Quickemu will
|
||
|
|
figure out the best way to do it for you.
|
||
|
|
For example:
|
||
|
|
.IP
|
||
|
|
.nf
|
||
|
|
\f[C]
|
||
|
|
quickget ubuntu-mate 21.10
|
||
|
|
quickemu --vm ubuntu-mate-21.10-.conf
|
||
|
|
\f[R]
|
||
|
|
.fi
|
||
|
|
.PP
|
||
|
|
The original objective of the project was to enable quick testing of
|
||
|
|
Linux distributions where the virtual machine configurations can be
|
||
|
|
stored anywhere, such as external USB storage or your home directory,
|
||
|
|
and no elevated permissions are required to run the virtual machines.
|
||
|
|
\f[B]Quickemu now also includes comprehensive support for macOS and
|
||
|
|
Windows\f[R].
|
||
|
|
.SS Features
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[B]macOS\f[R] Monterey, Big Sur, Catalina, Mojave & High Sierra
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[B]Windows\f[R] 8.1, 10 and 11 including TPM 2.0
|
||
|
|
.IP \[bu] 2
|
||
|
|
Ubuntu (https://ubuntu.com/desktop) and all the \f[B]official Ubuntu
|
||
|
|
flavours (https://ubuntu.com/download/flavours)\f[R]
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[B]Over 360 operating system editions are supported!\f[R]
|
||
|
|
.IP \[bu] 2
|
||
|
|
Full SPICE support including host/guest clipboard sharing
|
||
|
|
.IP \[bu] 2
|
||
|
|
VirtIO-webdavd file sharing for Linux and Windows guests
|
||
|
|
.IP \[bu] 2
|
||
|
|
VirtIO-9p file sharing for Linux and macOS guests
|
||
|
|
.IP \[bu] 2
|
||
|
|
QEMU Guest Agent support (https://wiki.qemu.org/Features/GuestAgent);
|
||
|
|
provides access to a system-level agent via standard QMP commands
|
||
|
|
.IP \[bu] 2
|
||
|
|
Samba file sharing for Linux, macOS and Windows guests (\f[I]if
|
||
|
|
\f[CI]smbd\f[I] is installed on the host\f[R])
|
||
|
|
.IP \[bu] 2
|
||
|
|
VirGL acceleration
|
||
|
|
.IP \[bu] 2
|
||
|
|
USB device pass-through
|
||
|
|
.IP \[bu] 2
|
||
|
|
Smartcard pass-through
|
||
|
|
.IP \[bu] 2
|
||
|
|
Automatic SSH port forwarding to guests
|
||
|
|
.IP \[bu] 2
|
||
|
|
Network port forwarding
|
||
|
|
.IP \[bu] 2
|
||
|
|
Full duplex audio
|
||
|
|
.IP \[bu] 2
|
||
|
|
Braille support
|
||
|
|
.IP \[bu] 2
|
||
|
|
EFI (with or without SecureBoot) and Legacy BIOS boot
|
||
|
|
.IP \[bu] 2
|
||
|
|
Graphical user interfaces available
|
||
|
|
.PP
|
||
|
|
Quickemu is a wrapper for the excellent QEMU (https://www.qemu.org/)
|
||
|
|
that attempts to automatically \f[I]\[lq]do the right thing\[rq]\f[R],
|
||
|
|
rather than expose exhaustive configuration options.
|
||
|
|
.PP
|
||
|
|
We have a Discord for this project:
|
||
|
|
[IMAGE: Discord (https://img.shields.io/discord/712850672223125565?color=0C306A&label=WimpysWorld%20Discord&logo=Discord&logoColor=ffffff&style=flat-square)] (https://discord.gg/sNmz3uw)
|
||
|
|
.PP
|
||
|
|
See this (old) video where I explain some of my motivations for creating
|
||
|
|
Quickemu.
|
||
|
|
.PP
|
||
|
|
[IMAGE: Replace VirtualBox with Bash &
|
||
|
|
QEMU (https://img.youtube.com/vi/AOTYWEgw0hI/0.jpg)] (https://www.youtube.com/watch?v=AOTYWEgw0hI)
|
||
|
|
.SS Requirements
|
||
|
|
.IP \[bu] 2
|
||
|
|
QEMU (https://www.qemu.org/) (\f[I]6.0.0 or newer\f[R]) \f[B]with GTK,
|
||
|
|
SDL, SPICE & VirtFS support\f[R]
|
||
|
|
.IP \[bu] 2
|
||
|
|
bash (https://www.gnu.org/software/bash/) (\f[I]4.0 or newer\f[R])
|
||
|
|
.IP \[bu] 2
|
||
|
|
Coreutils (https://www.gnu.org/software/coreutils/)
|
||
|
|
.IP \[bu] 2
|
||
|
|
EDK II (https://github.com/tianocore/edk2)
|
||
|
|
.IP \[bu] 2
|
||
|
|
grep (https://www.gnu.org/software/grep/)
|
||
|
|
.IP \[bu] 2
|
||
|
|
jq (https://stedolan.github.io/jq/)
|
||
|
|
.IP \[bu] 2
|
||
|
|
LSB (https://wiki.linuxfoundation.org/lsb/start)
|
||
|
|
.IP \[bu] 2
|
||
|
|
procps (https://gitlab.com/procps-ng/procps)
|
||
|
|
.IP \[bu] 2
|
||
|
|
python3 (https://www.python.org/)
|
||
|
|
.IP \[bu] 2
|
||
|
|
macrecovery (https://github.com/acidanthera/OpenCorePkg/tree/master/Utilities/macrecovery)
|
||
|
|
.IP \[bu] 2
|
||
|
|
mkisofs (http://cdrtools.sourceforge.net/private/cdrecord.html)
|
||
|
|
.IP \[bu] 2
|
||
|
|
usbutils (https://github.com/gregkh/usbutils)
|
||
|
|
.IP \[bu] 2
|
||
|
|
util-linux (https://github.com/karelzak/util-linux)
|
||
|
|
.IP \[bu] 2
|
||
|
|
sed (https://www.gnu.org/software/sed/)
|
||
|
|
.IP \[bu] 2
|
||
|
|
spicy (https://gitlab.freedesktop.org/spice/spice-gtk)
|
||
|
|
.IP \[bu] 2
|
||
|
|
swtpm (https://github.com/stefanberger/swtpm)
|
||
|
|
.IP \[bu] 2
|
||
|
|
Wget (https://www.gnu.org/software/wget/)
|
||
|
|
.IP \[bu] 2
|
||
|
|
xdg-user-dirs (https://www.freedesktop.org/wiki/Software/xdg-user-dirs/)
|
||
|
|
.IP \[bu] 2
|
||
|
|
xrandr (https://gitlab.freedesktop.org/xorg/app/xrandr)
|
||
|
|
.IP \[bu] 2
|
||
|
|
zsync (http://zsync.moria.org.uk/)
|
||
|
|
.SH Usage
|
||
|
|
.SS Graphical User Interfaces
|
||
|
|
.PP
|
||
|
|
While \f[C]quickemu\f[R] and \f[C]quickget\f[R] are designed for the
|
||
|
|
terminal, a graphical user interface is also available:
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[B]Quickgui (https://github.com/quickgui/quickgui)\f[R] by Mark
|
||
|
|
Johnson (https://github.com/marxjohnson) and Yannick
|
||
|
|
Mauray (https://github.com/ymauray).
|
||
|
|
.PP
|
||
|
|
Many thanks to Luke Wesley-Holley (https://github.com/Lukewh) and
|
||
|
|
Philipp Kiemle (https://github.com/daPhipz) for creating the
|
||
|
|
\f[B]Quickemu icons (https://github.com/Lukewh/quickemu-icons)\f[R]
|
||
|
|
\[u1F3A8]
|
||
|
|
.SS Quickgui for Ubuntu
|
||
|
|
.IP
|
||
|
|
.nf
|
||
|
|
\f[C]
|
||
|
|
sudo add-apt-repository ppa:yannick-mauray/quickgui
|
||
|
|
sudo apt update
|
||
|
|
sudo apt install quickgui
|
||
|
|
\f[R]
|
||
|
|
.fi
|
||
|
|
.SS Ubuntu Guest
|
||
|
|
.PP
|
||
|
|
\f[C]quickget\f[R] will automatically download an Ubuntu release and
|
||
|
|
create the virtual machine configuration.
|
||
|
|
.IP
|
||
|
|
.nf
|
||
|
|
\f[C]
|
||
|
|
quickget ubuntu 20.04
|
||
|
|
quickemu --vm ubuntu-20.04.conf
|
||
|
|
\f[R]
|
||
|
|
.fi
|
||
|
|
.IP \[bu] 2
|
||
|
|
Complete the installation as normal.
|
||
|
|
.IP \[bu] 2
|
||
|
|
Post-install:
|
||
|
|
.RS 2
|
||
|
|
.IP \[bu] 2
|
||
|
|
Install the SPICE agent (\f[C]spice-vdagent\f[R]) to enable copy/paste
|
||
|
|
and USB redirection
|
||
|
|
.RS 2
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]sudo apt install spice-vdagent\f[R]
|
||
|
|
.RE
|
||
|
|
.IP \[bu] 2
|
||
|
|
Install the SPICE WebDAV agent (\f[C]spice-webdavd\f[R]) to enable file
|
||
|
|
sharing.
|
||
|
|
.RS 2
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]sudo apt install spice-webdavd\f[R]
|
||
|
|
.RE
|
||
|
|
.RE
|
||
|
|
.SS Ubuntu devel (daily-live) images
|
||
|
|
.PP
|
||
|
|
\f[C]quickget\f[R] can also download/refresh devel images via
|
||
|
|
\f[C]zsync\f[R] for Ubuntu developers and testers.
|
||
|
|
.IP
|
||
|
|
.nf
|
||
|
|
\f[C]
|
||
|
|
quickget ubuntu devel
|
||
|
|
quickemu --vm ubuntu-devel.conf
|
||
|
|
\f[R]
|
||
|
|
.fi
|
||
|
|
.PP
|
||
|
|
You can run \f[C]quickget ubuntu devel\f[R] to refresh your daily
|
||
|
|
development image as often as you like, it will even automatically
|
||
|
|
switch to a new series.
|
||
|
|
.SS Ubuntu Flavours
|
||
|
|
.PP
|
||
|
|
All the official Ubuntu flavours are supported, just replace
|
||
|
|
\f[C]ubuntu\f[R] with your preferred flavour.
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]kubuntu\f[R] (Kubuntu)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]lubuntu\f[R] (Lubuntu)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]ubuntu-budgie\f[R] (Ubuntu Budgie)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]ubuntukylin\f[R] (Ubuntu Kylin)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]ubuntu-mate\f[R] (Ubuntu MATE)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]ubuntustudio\f[R] (Ubuntu Studio)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]ubuntu\f[R] (Ubuntu)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]xubuntu\f[R] (Xubuntu)
|
||
|
|
.SS Other Operating Systems
|
||
|
|
.PP
|
||
|
|
\f[C]quickget\f[R] also supports:
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]alma\f[R] (Alma Linux)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]alpine\f[R] (Alpine Linux)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]android\f[R] (Android x86)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]archlinux\f[R] (Arch Linux)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]arcolinux\f[R] (Arco Linux)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]cachyos\f[R] (CachyOS)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]debian\f[R] (Debian)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]devuan\f[R] (Devuan)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]dragonflybsd\f[R] (DragonFlyBSD)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]elementary\f[R] (elementary OS)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]fedora\f[R] (Fedora)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]freebsd\f[R] (FreeBSD)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]garuda\f[R] (Garuda Linux)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]gentoo\f[R] (Gentoo)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]ghostbsd\f[R] (GhostBSD)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]haiku\f[R] (Haiku)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]kali\f[R] (Kali)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]kdeneon\f[R] (KDE Neon)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]kolibrios\f[R] (KolibriOS)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]linuxmint\f[R] (Linux Mint)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]manjaro\f[R] (Manjaro)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]mxlinux\f[R] (MX Linux)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]netboot\f[R] (netboot.xyz)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]netbsd\f[R] (NetBSD)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]nixos\f[R] (NixOS)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]openbsd\f[R] (OpenBSD)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]opensuse\f[R] (openSUSE)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]oraclelinux\f[R] (Oracle Linux)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]popos\f[R] (Pop!_OS)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]regolith\f[R] (Regolith Linux)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]rockylinux\f[R] (Rocky Linux)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]slackware\f[R] (Slackware)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]solus\f[R] (Solus)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]tails\f[R] (Tails)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]void\f[R] (Void Linux)
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]zorin\f[R] (Zorin OS)
|
||
|
|
.PP
|
||
|
|
Or you can download a Linux image and manually create a VM
|
||
|
|
configuration.
|
||
|
|
.IP \[bu] 2
|
||
|
|
Download a .iso image of a Linux distribution
|
||
|
|
.IP \[bu] 2
|
||
|
|
Create a VM configuration file; for example
|
||
|
|
\f[C]debian-bullseye.conf\f[R]
|
||
|
|
.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
|
||
|
|
.IP \[bu] 2
|
||
|
|
Use \f[C]quickemu\f[R] to start the virtual machine:
|
||
|
|
.IP
|
||
|
|
.nf
|
||
|
|
\f[C]
|
||
|
|
quickemu --vm debian-bullseye.conf
|
||
|
|
\f[R]
|
||
|
|
.fi
|
||
|
|
.IP \[bu] 2
|
||
|
|
Complete the installation as normal.
|
||
|
|
.IP \[bu] 2
|
||
|
|
Post-install:
|
||
|
|
.RS 2
|
||
|
|
.IP \[bu] 2
|
||
|
|
Install the SPICE agent (\f[C]spice-vdagent\f[R]) to enable copy/paste
|
||
|
|
and USB redirection.
|
||
|
|
.IP \[bu] 2
|
||
|
|
Install the SPICE WebDAV agent (\f[C]spice-webdavd\f[R]) to enable file
|
||
|
|
sharing.
|
||
|
|
.RE
|
||
|
|
.SS macOS Guest
|
||
|
|
.PP
|
||
|
|
\f[C]quickget\f[R] automatically downloads a macOS recovery image and
|
||
|
|
creates a virtual machine configuration.
|
||
|
|
.IP
|
||
|
|
.nf
|
||
|
|
\f[C]
|
||
|
|
quickget macos catalina
|
||
|
|
quickemu --vm macos-catalina.conf
|
||
|
|
\f[R]
|
||
|
|
.fi
|
||
|
|
.PP
|
||
|
|
macOS \f[C]high-sierra\f[R], \f[C]mojave\f[R], \f[C]catalina\f[R],
|
||
|
|
\f[C]big-sur\f[R] and \f[C]monterey\f[R] are supported.
|
||
|
|
.IP \[bu] 2
|
||
|
|
Use cursor keys and enter key to select the \f[B]macOS Base System\f[R]
|
||
|
|
.IP \[bu] 2
|
||
|
|
From \f[B]macOS Utilities\f[R]
|
||
|
|
.RS 2
|
||
|
|
.IP \[bu] 2
|
||
|
|
Click \f[B]Disk Utility\f[R] and \f[B]Continue\f[R]
|
||
|
|
.RS 2
|
||
|
|
.IP \[bu] 2
|
||
|
|
On macOS Catalina, Big Sur & Monterey
|
||
|
|
.RS 2
|
||
|
|
.IP \[bu] 2
|
||
|
|
Select \f[C]Apple Inc. VirtIO Block Media\f[R] from the list and click
|
||
|
|
\f[B]Erase\f[R].
|
||
|
|
.RE
|
||
|
|
.IP \[bu] 2
|
||
|
|
On macOS Mojave and High Sierra
|
||
|
|
.RS 2
|
||
|
|
.IP \[bu] 2
|
||
|
|
Select \f[C]QEMU HARDDISK Media\f[R] (\[ti]103.08GB) from the list and
|
||
|
|
click \f[B]Erase\f[R].
|
||
|
|
.RE
|
||
|
|
.RE
|
||
|
|
.IP \[bu] 2
|
||
|
|
Enter a \f[C]Name:\f[R] for the disk and click \f[B]Erase\f[R].
|
||
|
|
.IP \[bu] 2
|
||
|
|
Click \f[B]Done\f[R].
|
||
|
|
.IP \[bu] 2
|
||
|
|
Close Disk Utility
|
||
|
|
.RE
|
||
|
|
.IP \[bu] 2
|
||
|
|
From \f[B]macOS Utilities\f[R]
|
||
|
|
.RS 2
|
||
|
|
.IP \[bu] 2
|
||
|
|
Click \f[B]Reinstall macOS\f[R] and \f[B]Continue\f[R]
|
||
|
|
.RE
|
||
|
|
.IP \[bu] 2
|
||
|
|
Complete the installation as you normally would.
|
||
|
|
.RS 2
|
||
|
|
.IP \[bu] 2
|
||
|
|
On the first reboot use cursor keys and enter key to select \f[B]macOS
|
||
|
|
Installer\f[R]
|
||
|
|
.IP \[bu] 2
|
||
|
|
On the subsequent reboots use cursor keys and enter key to select the
|
||
|
|
disk you named
|
||
|
|
.RE
|
||
|
|
.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[C]guest_os=\[dq]macos\[dq]\f[R] instructs Quickemu to optimise for
|
||
|
|
macOS.
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]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
|
||
|
|
.SS macOS compatibility
|
||
|
|
.PP
|
||
|
|
There are some considerations when running macOS via Quickemu.
|
||
|
|
.IP \[bu] 2
|
||
|
|
Supported macOS releases:
|
||
|
|
.RS 2
|
||
|
|
.IP \[bu] 2
|
||
|
|
High Sierra
|
||
|
|
.IP \[bu] 2
|
||
|
|
Mojave
|
||
|
|
.IP \[bu] 2
|
||
|
|
Catalina \f[B](Recommended)\f[R]
|
||
|
|
.IP \[bu] 2
|
||
|
|
Big Sur
|
||
|
|
.IP \[bu] 2
|
||
|
|
Monterey
|
||
|
|
.RE
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]quickemu\f[R] will automatically download the required
|
||
|
|
OpenCore (https://github.com/acidanthera/OpenCorePkg) bootloader and
|
||
|
|
OVMF firmware from OSX-KVM (https://github.com/kholia/OSX-KVM).
|
||
|
|
.IP \[bu] 2
|
||
|
|
Optimised by default, but no GPU acceleration is available.
|
||
|
|
.RS 2
|
||
|
|
.IP \[bu] 2
|
||
|
|
Host CPU vendor is detected and guest CPU is optimised accordingly.
|
||
|
|
.IP \[bu] 2
|
||
|
|
VirtIO Block
|
||
|
|
Media (https://www.kraxel.org/blog/2019/06/macos-qemu-guest/) is used
|
||
|
|
for the system disk where supported.
|
||
|
|
.IP \[bu] 2
|
||
|
|
VirtIO \f[C]usb-tablet\f[R] (http://philjordan.eu/osx-virt/) is used for
|
||
|
|
the mouse.
|
||
|
|
.IP \[bu] 2
|
||
|
|
VirtIO Network (\f[C]virtio-net\f[R]) is supported and enabled on macOS
|
||
|
|
Big Sur and newer but previous releases use \f[C]vmxnet3\f[R].
|
||
|
|
.IP \[bu] 2
|
||
|
|
VirtIO Memory Ballooning is supported and enabled on macOS Big Sur and
|
||
|
|
newer but disabled for other support macOS releases.
|
||
|
|
.RE
|
||
|
|
.IP \[bu] 2
|
||
|
|
USB host and SPICE pass-through is:
|
||
|
|
.RS 2
|
||
|
|
.IP \[bu] 2
|
||
|
|
UHCI (USB 2.0) on macOS Catalina and earlier.
|
||
|
|
.IP \[bu] 2
|
||
|
|
XHCI (USB 3.0) on macOS Big Sur and newer.
|
||
|
|
.RE
|
||
|
|
.IP \[bu] 2
|
||
|
|
Display resolution can only be changed via macOS System Preferences.
|
||
|
|
.IP \[bu] 2
|
||
|
|
Full Duplex audio works on macOS High Sierra, Mojave and Catalina.
|
||
|
|
.RS 2
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[B]macOS Big Sur and Monterey have no audio at all\f[R].
|
||
|
|
.RE
|
||
|
|
.IP \[bu] 2
|
||
|
|
File sharing between guest and host is available via
|
||
|
|
virtio-9p (https://wiki.qemu.org/Documentation/9psetup) and SPICE
|
||
|
|
webdavd (https://gitlab.gnome.org/GNOME/phodav/-/merge_requests/24).
|
||
|
|
.IP \[bu] 2
|
||
|
|
Copy/paste via SPICE agent is \f[B]not available on macOS\f[R].
|
||
|
|
.SS Windows 8.1, 10 & 11 Guests
|
||
|
|
.PP
|
||
|
|
\f[C]quickget\f[R] can automatically download Windows 8.1, Windows
|
||
|
|
10 (https://www.microsoft.com/en-gb/software-download/windows10ISO) and
|
||
|
|
Windows 11 (https://www.microsoft.com/en-gb/software-download/windows11)
|
||
|
|
along with the VirtIO drivers for
|
||
|
|
Windows (https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/)
|
||
|
|
and creates a virtual machine configuration.
|
||
|
|
.IP
|
||
|
|
.nf
|
||
|
|
\f[C]
|
||
|
|
quickget windows 11
|
||
|
|
quickemu --vm windows-11.conf
|
||
|
|
\f[R]
|
||
|
|
.fi
|
||
|
|
.IP \[bu] 2
|
||
|
|
Complete the installation as you normally would.
|
||
|
|
.IP \[bu] 2
|
||
|
|
All relevant drivers and services should be installed automatically.
|
||
|
|
.SS Regional versions
|
||
|
|
.PP
|
||
|
|
By default \f[C]quickget\f[R] will download the \f[I]\[lq]English
|
||
|
|
International\[rq]\f[R] release, but you can optionally specify one of
|
||
|
|
the supported languages: For example:
|
||
|
|
.IP
|
||
|
|
.nf
|
||
|
|
\f[C]
|
||
|
|
quickget windows 11 \[dq]Chinese (Traditional)\[dq]
|
||
|
|
\f[R]
|
||
|
|
.fi
|
||
|
|
.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]
|
||
|
|
\f[R]
|
||
|
|
.fi
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]guest_os=\[dq]windows\[dq]\f[R] instructs \f[C]quickemu\f[R] to
|
||
|
|
optimise for Windows.
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]fixed_iso=\f[R] specifies the ISO image that provides VirtIO
|
||
|
|
drivers.
|
||
|
|
.IP \[bu] 2
|
||
|
|
\f[C]tpm=\[dq]on\[dq]\f[R] instructs \f[C]quickemu\f[R] to create a
|
||
|
|
software emulated TPM device using \f[C]swtpm\f[R].
|
||
|
|
.SH All the options
|
||
|
|
.PP
|
||
|
|
Here are the usage instructions:
|
||
|
|
.IP
|
||
|
|
.nf
|
||
|
|
\f[C]
|
||
|
|
|
||
|
|
Usage
|
||
|
|
quickemu --vm ubuntu.conf
|
||
|
|
|
||
|
|
You can also pass optional parameters
|
||
|
|
--braille : Enable braille support. Requires SDL.
|
||
|
|
--delete-disk : Delete the disk image and EFI variables
|
||
|
|
--delete-vm : Delete the entire VM and it\[aq]s configuration
|
||
|
|
--display : Select display backend. \[aq]sdl\[aq] (default), \[aq]gtk\[aq], \[aq]none\[aq], or \[aq]spice\[aq]
|
||
|
|
--fullscreen : Starts VM in full screen mode (Ctl+Alt+f to exit)
|
||
|
|
--ignore-msrs-always : Configure KVM to always ignore unhandled machine-specific registers
|
||
|
|
--screen <screen> : Use specified screen to determine the window size.
|
||
|
|
--shortcut : Create a desktop shortcut
|
||
|
|
--snapshot apply <tag> : Apply/restore a snapshot.
|
||
|
|
--snapshot create <tag> : Create a snapshot.
|
||
|
|
--snapshot delete <tag> : Delete a snapshot.
|
||
|
|
--snapshot info : Show disk/snapshot info.
|
||
|
|
--status-quo : Do not commit any changes to disk/snapshot.
|
||
|
|
--version : Print version
|
||
|
|
|
||
|
|
\f[R]
|
||
|
|
.fi
|
||
|
|
.SS Desktop shortcuts
|
||
|
|
.PP
|
||
|
|
Desktop shortcuts can be created for a VM, the shortcuts are saved in
|
||
|
|
\f[C]\[ti]/.local/share/applications\f[R].
|
||
|
|
Here is an example of how to create a shortcut.
|
||
|
|
.IP
|
||
|
|
.nf
|
||
|
|
\f[C]
|
||
|
|
quickemu --vm ubuntu-20.04-desktop.conf --shortcut
|
||
|
|
\f[R]
|
||
|
|
.fi
|
||
|
|
.SS Screen and window size (Linux guests only)
|
||
|
|
.PP
|
||
|
|
\f[C]qemu\f[R] will always default to the primary monitor to display the
|
||
|
|
VM\[cq]s window.
|
||
|
|
.PP
|
||
|
|
Without the \f[C]--screen\f[R] option, \f[C]quickemu\f[R] will look for
|
||
|
|
the size of the smallest monitor, and use a size that fits on said
|
||
|
|
monitor.
|
||
|
|
.PP
|
||
|
|
The \f[C]--screen\f[R] option forces \f[C]quickemu\f[R] to use the size
|
||
|
|
of the given monitor to compute the size of the window.
|
||
|
|
\f[B]It won\[cq]t use that monitor to display the VM\[cq]s window if
|
||
|
|
it\[cq]s not the primary monitor\f[R].
|
||
|
|
This is useful if the primary monitor if not the smallest one, and if
|
||
|
|
the VM\[cq]s window doesn\[cq]t need to be moved around.
|
||
|
|
.PP
|
||
|
|
The \f[C]--screen\f[R] option is also useful with the
|
||
|
|
\f[C]--fullscreen\f[R] option, again because \f[C]qemu\f[R] will always
|
||
|
|
use the primary monitor.
|
||
|
|
In order for the fullscreen mode to work properly, the resolution of the
|
||
|
|
VM\[cq]s window must match the resolution of the screen.
|
||
|
|
.PP
|
||
|
|
To know which screen to use, type:
|
||
|
|
.IP
|
||
|
|
.nf
|
||
|
|
\f[C]
|
||
|
|
xrandr --listmonitors | grep -v Monitors
|
||
|
|
\f[R]
|
||
|
|
.fi
|
||
|
|
.PP
|
||
|
|
The command will output something like this:
|
||
|
|
.IP
|
||
|
|
.nf
|
||
|
|
\f[C]
|
||
|
|
0: +*HDMI-0 2560/597x1440/336+1920+0 HDMI-0
|
||
|
|
1: +DVI-D-0 1920/527x1080/296+0+0 DVI-D-0
|
||
|
|
\f[R]
|
||
|
|
.fi
|
||
|
|
.PP
|
||
|
|
The first number is what needs to be passed to the \f[C]--screen\f[R]
|
||
|
|
option.
|
||
|
|
.PP
|
||
|
|
For example:
|
||
|
|
.IP
|
||
|
|
.nf
|
||
|
|
\f[C]
|
||
|
|
quickemu --vm vm.conf --screen 0
|
||
|
|
\f[R]
|
||
|
|
.fi
|
||
|
|
.PP
|
||
|
|
The above uses the 2560x1440 screen to compute the size of the window,
|
||
|
|
which Quickemu sizes to 2048x1152.
|
||
|
|
Without the \f[C]--screen\f[R] option, Quickemu would have used the
|
||
|
|
1920x1080 monitor which results in a window size of 1664x936.
|
||
|
|
.SH References
|
||
|
|
.PP
|
||
|
|
Useful reference that assisted the development of Quickemu.
|
||
|
|
.IP \[bu] 2
|
||
|
|
General
|
||
|
|
.RS 2
|
||
|
|
.IP \[bu] 2
|
||
|
|
QEMU\[cq]s documentation! (https://qemu.readthedocs.io/en/latest/)
|
||
|
|
.IP \[bu] 2
|
||
|
|
<https://pve.proxmox.com/wiki/Qemu/KVM_Virtual_Machines>
|
||
|
|
.IP \[bu] 2
|
||
|
|
<https://www.kraxel.org/blog/2020/01/qemu-sound-audiodev/>
|
||
|
|
.RE
|
||
|
|
.IP \[bu] 2
|
||
|
|
macOS
|
||
|
|
.RS 2
|
||
|
|
.IP \[bu] 2
|
||
|
|
<https://www.nicksherlock.com/2020/06/installing-macos-big-sur-on-proxmox/>
|
||
|
|
.IP \[bu] 2
|
||
|
|
<https://passthroughpo.st/mac-os-adds-early-support-for-virtio-qemu/>
|
||
|
|
.IP \[bu] 2
|
||
|
|
<https://github.com/kholia/OSX-KVM>
|
||
|
|
.IP \[bu] 2
|
||
|
|
<https://github.com/thenickdude/KVM-Opencore>
|
||
|
|
.IP \[bu] 2
|
||
|
|
<https://github.com/acidanthera/OpenCorePkg/tree/master/Utilities/macrecovery>
|
||
|
|
.IP \[bu] 2
|
||
|
|
<https://www.kraxel.org/blog/2017/09/running-macos-as-guest-in-kvm/>
|
||
|
|
.IP \[bu] 2
|
||
|
|
<https://www.nicksherlock.com/2017/10/passthrough-of-advanced-cpu-features-for-macos-high-sierra-guests/>
|
||
|
|
.IP \[bu] 2
|
||
|
|
<http://philjordan.eu/osx-virt/>
|
||
|
|
.IP \[bu] 2
|
||
|
|
<https://github.com/Dids/clover-builder>
|
||
|
|
.IP \[bu] 2
|
||
|
|
OpenCore Configurator (https://mackie100projects.altervista.org)
|
||
|
|
.RE
|
||
|
|
.IP \[bu] 2
|
||
|
|
Windows
|
||
|
|
.RS 2
|
||
|
|
.IP \[bu] 2
|
||
|
|
<https://www.heiko-sieger.info/running-windows-10-on-linux-using-kvm-with-vga-passthrough/>
|
||
|
|
.IP \[bu] 2
|
||
|
|
<https://leduccc.medium.com/improving-the-performance-of-a-windows-10-guest-on-qemu-a5b3f54d9cf5>
|
||
|
|
.IP \[bu] 2
|
||
|
|
<https://frontpagelinux.com/tutorials/how-to-use-linux-kvm-to-optimize-your-windows-10-virtual-machine/>
|
||
|
|
.IP \[bu] 2
|
||
|
|
<https://turlucode.com/qemu-command-line-args/>
|
||
|
|
.IP \[bu] 2
|
||
|
|
<https://github.com/pbatard/Fido>
|
||
|
|
.IP \[bu] 2
|
||
|
|
<https://www.catapultsystems.com/blogs/create-zero-touch-windows-10-iso/>
|
||
|
|
.RE
|
||
|
|
.IP \[bu] 2
|
||
|
|
TPM
|
||
|
|
.RS 2
|
||
|
|
.IP \[bu] 2
|
||
|
|
<https://qemu-project.gitlab.io/qemu/specs/tpm.html>
|
||
|
|
.IP \[bu] 2
|
||
|
|
<https://www.tecklyfe.com/how-to-create-a-windows-11-virtual-machine-in-qemu/>
|
||
|
|
.RE
|
||
|
|
.IP \[bu] 2
|
||
|
|
9p & virtiofs
|
||
|
|
.RS 2
|
||
|
|
.IP \[bu] 2
|
||
|
|
<https://wiki.qemu.org/Documentation/9p>
|
||
|
|
.IP \[bu] 2
|
||
|
|
<https://wiki.qemu.org/Documentation/9psetup>
|
||
|
|
.IP \[bu] 2
|
||
|
|
<https://www.kraxel.org/blog/2019/06/macos-qemu-guest/>
|
||
|
|
.IP \[bu] 2
|
||
|
|
<https://superuser.com/questions/628169/how-to-share-a-directory-with-the-host-without-networking-in-qemu>
|
||
|
|
.IP \[bu] 2
|
||
|
|
<https://virtio-fs.gitlab.io/>
|
||
|
|
.RE
|
||
|
|
.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
|
||
|
|
quickemu_conf(1), quickget(1), quickgui(1)
|
||
|
|
.SH AUTHORS
|
||
|
|
Martin Wimpress.
|