Add docs folder (#366)
* generated man pages added
* updated dates and tidy footers
* reflect removal of localiso feature
* trying to keep up... re-generating
* merged up to 4ec224c
and regenerated
* minor removal ommission fixed
* Regenerated README.md added
only significant difference is Slackware display name is
as per quickget
* change variant to edition per refactoring
* updated manuals with new braille parameter
* updated generated Readme with new braille parameter
* keepeing up
* revert README.md to upstream for noise-suppression
* fixed pretty name issue in manuals
* fixed pretty name issues in Readme
* fixed conflict
* update ubuntu releases from name to number
pull/404/head
parent
03c5b9fc52
commit
47b2479d92
@ -0,0 +1,42 @@ |
|||||||
|
include pandoc-man.mk |
||||||
|
|
||||||
|
ifeq ($(PREFIX),) |
||||||
|
PREFIX := /usr/local
|
||||||
|
endif |
||||||
|
|
||||||
|
datarootdir := $(PREFIX)/share
|
||||||
|
datadir := $(datarootdir)
|
||||||
|
mandir := $(datarootdir)/man
|
||||||
|
bindir := $(PREFIX)/bin
|
||||||
|
|
||||||
|
all: quickget.1 quickemu.1 quickemu_conf.1 |
||||||
|
|
||||||
|
clean: |
||||||
|
rm *.1
|
||||||
|
|
||||||
|
install_docs: all |
||||||
|
install -d $(DESTDIR)$(mandir)/man1
|
||||||
|
install -m 644 quickget.1 $(DESTDIR)$(mandir)/man1
|
||||||
|
install -m 644 quickemu.1 $(DESTDIR)$(mandir)/man1
|
||||||
|
install -m 644 quickemu_conf.1 $(DESTDIR)$(mandir)/man1
|
||||||
|
|
||||||
|
# install -m 644 quickgui.1 $(DESTDIR)$(mandir)/man1
|
||||||
|
|
||||||
|
install_bins: |
||||||
|
install -d $(DESTDIR)$(bindir)
|
||||||
|
install -m 755 ../quickget $(DESTDIR)$(bindir)
|
||||||
|
install -m 755 ../quickemu $(DESTDIR)$(bindir)
|
||||||
|
install -m 755 ../macrecovery $(DESTDIR)$(bindir)
|
||||||
|
|
||||||
|
install: install_bins install_docs |
||||||
|
|
||||||
|
uninstall:: |
||||||
|
rm -f $(DESTDIR)$(mandir)/man1/quickget.1
|
||||||
|
rm -f $(DESTDIR)$(mandir)/man1/quickemu.1
|
||||||
|
rm -f $(DESTDIR)$(mandir)/man1/quickemu_conf.1
|
||||||
|
rm -f $(DESTDIR)$(bindir)/quickget
|
||||||
|
rm -f $(DESTDIR)$(bindir)/quickemu
|
||||||
|
rm -f $(DESTDIR)$(bindir)/macrecovery
|
||||||
|
|
||||||
|
|
||||||
|
.PHONY: all |
@ -0,0 +1,8 @@ |
|||||||
|
PANDOC ?= pandoc
|
||||||
|
|
||||||
|
MANSECTION ?= 1
|
||||||
|
|
||||||
|
MANPAGE.md = $(PANDOC) --standalone $(PANDOCFLAGS) --to man
|
||||||
|
|
||||||
|
%.$(MANSECTION): %.$(MANSECTION).md |
||||||
|
$(MANPAGE.md) $< -o $@
|
@ -0,0 +1,761 @@ |
|||||||
|
.\" 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. |
@ -0,0 +1,573 @@ |
|||||||
|
--- |
||||||
|
author: Martin Wimpress |
||||||
|
date: 'February 20, 2022' |
||||||
|
footer: quickemu |
||||||
|
header: Quickemu User Manual |
||||||
|
section: 1 |
||||||
|
title: QUICKEMU |
||||||
|
--- |
||||||
|
|
||||||
|
NAME |
||||||
|
==== |
||||||
|
|
||||||
|
quickemu - A quick VM builder and manager |
||||||
|
|
||||||
|
SYNOPSIS |
||||||
|
======== |
||||||
|
|
||||||
|
**quickemu** \[*OPTION*\]... |
||||||
|
|
||||||
|
DESCRIPTION |
||||||
|
=========== |
||||||
|
|
||||||
|
**quickemu** will create and run highly optimised desktop virtual |
||||||
|
machines for Linux, macOS and Windows |
||||||
|
|
||||||
|
OPTIONS |
||||||
|
======= |
||||||
|
|
||||||
|
**--vm** |
||||||
|
: vm configuration file |
||||||
|
|
||||||
|
You can also pass optional parameters |
||||||
|
|
||||||
|
**--braille** |
||||||
|
: Enable braille support. Requires SDL. |
||||||
|
|
||||||
|
**--delete** |
||||||
|
: Delete the disk image. |
||||||
|
|
||||||
|
**--display** |
||||||
|
: Select display backend. 'sdl' (default), 'gtk', 'none' or 'spice' |
||||||
|
|
||||||
|
**--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 |
||||||
|
|
||||||
|
EXAMPLES |
||||||
|
======== |
||||||
|
|
||||||
|
**quickemu --vm ubuntu-mate-21.10-.conf** |
||||||
|
: Launches the VM specified in the file *ubuntu-mate-21.10-.conf* |
||||||
|
|
||||||
|
Introduction |
||||||
|
------------ |
||||||
|
|
||||||
|
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: |
||||||
|
|
||||||
|
``` {.bash} |
||||||
|
quickget ubuntu-mate 21.10 |
||||||
|
quickemu --vm ubuntu-mate-21.10-.conf |
||||||
|
``` |
||||||
|
|
||||||
|
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. |
||||||
|
**Quickemu now also includes comprehensive support for macOS and |
||||||
|
Windows**. |
||||||
|
|
||||||
|
Features |
||||||
|
-------- |
||||||
|
|
||||||
|
- **macOS** Monterey, Big Sur, Catalina, Mojave & High Sierra |
||||||
|
- **Windows** 8.1, 10 and 11 including TPM 2.0 |
||||||
|
- [Ubuntu](https://ubuntu.com/desktop) and all the **[official Ubuntu |
||||||
|
flavours](https://ubuntu.com/download/flavours)** |
||||||
|
- **Over 360 operating system editions are supported!** |
||||||
|
- Full SPICE support including host/guest clipboard sharing |
||||||
|
- VirtIO-webdavd file sharing for Linux and Windows guests |
||||||
|
- VirtIO-9p file sharing for Linux and macOS guests |
||||||
|
- [QEMU Guest Agent |
||||||
|
support](https://wiki.qemu.org/Features/GuestAgent); provides access |
||||||
|
to a system-level agent via standard QMP commands |
||||||
|
- Samba file sharing for Linux, macOS and Windows guests (*if `smbd` |
||||||
|
is installed on the host*) |
||||||
|
- VirGL acceleration |
||||||
|
- USB device pass-through |
||||||
|
- Smartcard pass-through |
||||||
|
- Automatic SSH port forwarding to guests |
||||||
|
- Network port forwarding |
||||||
|
- Full duplex audio |
||||||
|
- Braille support |
||||||
|
- EFI (with or without SecureBoot) and Legacy BIOS boot |
||||||
|
- Graphical user interfaces available |
||||||
|
|
||||||
|
Quickemu is a wrapper for the excellent [QEMU](https://www.qemu.org/) |
||||||
|
that attempts to automatically *"do the right thing"*, rather than |
||||||
|
expose exhaustive configuration options. |
||||||
|
|
||||||
|
We have a Discord for this project: |
||||||
|
[![Discord](https://img.shields.io/discord/712850672223125565?color=0C306A&label=WimpysWorld%20Discord&logo=Discord&logoColor=ffffff&style=flat-square)](https://discord.gg/sNmz3uw) |
||||||
|
|
||||||
|
See this (old) video where I explain some of my motivations for creating |
||||||
|
Quickemu. |
||||||
|
|
||||||
|
[![Replace VirtualBox with Bash & |
||||||
|
QEMU](https://img.youtube.com/vi/AOTYWEgw0hI/0.jpg)](https://www.youtube.com/watch?v=AOTYWEgw0hI) |
||||||
|
|
||||||
|
Requirements |
||||||
|
------------ |
||||||
|
|
||||||
|
- [QEMU](https://www.qemu.org/) (*6.0.0 or newer*) **with GTK, SDL, |
||||||
|
SPICE & VirtFS support** |
||||||
|
- [bash](https://www.gnu.org/software/bash/) (*4.0 or newer*) |
||||||
|
- [Coreutils](https://www.gnu.org/software/coreutils/) |
||||||
|
- [EDK II](https://github.com/tianocore/edk2) |
||||||
|
- [grep](https://www.gnu.org/software/grep/) |
||||||
|
- [jq](https://stedolan.github.io/jq/) |
||||||
|
- [LSB](https://wiki.linuxfoundation.org/lsb/start) |
||||||
|
- [procps](https://gitlab.com/procps-ng/procps) |
||||||
|
- [python3](https://www.python.org/) |
||||||
|
- [macrecovery](https://github.com/acidanthera/OpenCorePkg/tree/master/Utilities/macrecovery) |
||||||
|
- [mkisofs](http://cdrtools.sourceforge.net/private/cdrecord.html) |
||||||
|
- [usbutils](https://github.com/gregkh/usbutils) |
||||||
|
- [util-linux](https://github.com/karelzak/util-linux) |
||||||
|
- [sed](https://www.gnu.org/software/sed/) |
||||||
|
- [spicy](https://gitlab.freedesktop.org/spice/spice-gtk) |
||||||
|
- [swtpm](https://github.com/stefanberger/swtpm) |
||||||
|
- [Wget](https://www.gnu.org/software/wget/) |
||||||
|
- [xdg-user-dirs](https://www.freedesktop.org/wiki/Software/xdg-user-dirs/) |
||||||
|
- [xrandr](https://gitlab.freedesktop.org/xorg/app/xrandr) |
||||||
|
- [zsync](http://zsync.moria.org.uk/) |
||||||
|
|
||||||
|
Usage |
||||||
|
===== |
||||||
|
|
||||||
|
Graphical User Interfaces |
||||||
|
------------------------- |
||||||
|
|
||||||
|
While `quickemu` and `quickget` are designed for the terminal, a |
||||||
|
graphical user interface is also available: |
||||||
|
|
||||||
|
- **[Quickgui](https://github.com/quickgui/quickgui)** by [Mark |
||||||
|
Johnson](https://github.com/marxjohnson) and [Yannick |
||||||
|
Mauray](https://github.com/ymauray). |
||||||
|
|
||||||
|
Many thanks to [Luke Wesley-Holley](https://github.com/Lukewh) and |
||||||
|
[Philipp Kiemle](https://github.com/daPhipz) for creating the |
||||||
|
**[Quickemu icons](https://github.com/Lukewh/quickemu-icons)** 🎨 |
||||||
|
|
||||||
|
### Quickgui for Ubuntu |
||||||
|
|
||||||
|
``` {.bash} |
||||||
|
sudo add-apt-repository ppa:yannick-mauray/quickgui |
||||||
|
sudo apt update |
||||||
|
sudo apt install quickgui |
||||||
|
``` |
||||||
|
|
||||||
|
Ubuntu Guest |
||||||
|
------------ |
||||||
|
|
||||||
|
`quickget` will automatically download an Ubuntu release and create the |
||||||
|
virtual machine configuration. |
||||||
|
|
||||||
|
``` {.bash} |
||||||
|
quickget ubuntu 20.04 |
||||||
|
quickemu --vm ubuntu-20.04.conf |
||||||
|
``` |
||||||
|
|
||||||
|
- Complete the installation as normal. |
||||||
|
- Post-install: |
||||||
|
- Install the SPICE agent (`spice-vdagent`) to enable copy/paste |
||||||
|
and USB redirection |
||||||
|
- `sudo apt install spice-vdagent` |
||||||
|
- Install the SPICE WebDAV agent (`spice-webdavd`) to enable file |
||||||
|
sharing. |
||||||
|
- `sudo apt install spice-webdavd` |
||||||
|
|
||||||
|
### Ubuntu devel (daily-live) images |
||||||
|
|
||||||
|
`quickget` can also download/refresh devel images via `zsync` for Ubuntu |
||||||
|
developers and testers. |
||||||
|
|
||||||
|
``` {.bash} |
||||||
|
quickget ubuntu devel |
||||||
|
quickemu --vm ubuntu-devel.conf |
||||||
|
``` |
||||||
|
|
||||||
|
You can run `quickget ubuntu devel` to refresh your daily development |
||||||
|
image as often as you like, it will even automatically switch to a new |
||||||
|
series. |
||||||
|
|
||||||
|
### Ubuntu Flavours |
||||||
|
|
||||||
|
All the official Ubuntu flavours are supported, just replace `ubuntu` |
||||||
|
with your preferred flavour. |
||||||
|
|
||||||
|
- `kubuntu` (Kubuntu) |
||||||
|
- `lubuntu` (Lubuntu) |
||||||
|
- `ubuntu-budgie` (Ubuntu Budgie) |
||||||
|
- `ubuntukylin` (Ubuntu Kylin) |
||||||
|
- `ubuntu-mate` (Ubuntu MATE) |
||||||
|
- `ubuntustudio` (Ubuntu Studio) |
||||||
|
- `ubuntu` (Ubuntu) |
||||||
|
- `xubuntu` (Xubuntu) |
||||||
|
|
||||||
|
Other Operating Systems |
||||||
|
----------------------- |
||||||
|
|
||||||
|
`quickget` also supports: |
||||||
|
|
||||||
|
- `alma` (Alma Linux) |
||||||
|
- `alpine` (Alpine Linux) |
||||||
|
- `android` (Android x86) |
||||||
|
- `archlinux` (Arch Linux) |
||||||
|
- `arcolinux` (Arco Linux) |
||||||
|
- `cachyos` (CachyOS) |
||||||
|
- `debian` (Debian) |
||||||
|
- `devuan` (Devuan) |
||||||
|
- `dragonflybsd` (DragonFlyBSD) |
||||||
|
- `elementary` (elementary OS) |
||||||
|
- `fedora` (Fedora) |
||||||
|
- `freebsd` (FreeBSD) |
||||||
|
- `garuda` (Garuda Linux) |
||||||
|
- `gentoo` (Gentoo) |
||||||
|
- `ghostbsd` (GhostBSD) |
||||||
|
- `haiku` (Haiku) |
||||||
|
- `kali` (Kali) |
||||||
|
- `kdeneon` (KDE Neon) |
||||||
|
- `kolibrios` (KolibriOS) |
||||||
|
- `linuxmint` (Linux Mint) |
||||||
|
- `manjaro` (Manjaro) |
||||||
|
- `mxlinux` (MX Linux) |
||||||
|
- `netboot` (netboot.xyz) |
||||||
|
- `netbsd` (NetBSD) |
||||||
|
- `nixos` (NixOS) |
||||||
|
- `openbsd` (OpenBSD) |
||||||
|
- `opensuse` (openSUSE) |
||||||
|
- `oraclelinux` (Oracle Linux) |
||||||
|
- `popos` (Pop!\_OS) |
||||||
|
- `regolith` (Regolith Linux) |
||||||
|
- `rockylinux` (Rocky Linux) |
||||||
|
- `slackware` (Slackware) |
||||||
|
- `solus` (Solus) |
||||||
|
- `tails` (Tails) |
||||||
|
- `void` (Void Linux) |
||||||
|
- `zorin` (Zorin OS) |
||||||
|
|
||||||
|
Or you can download a Linux image and manually create a VM |
||||||
|
configuration. |
||||||
|
|
||||||
|
- Download a .iso image of a Linux distribution |
||||||
|
- Create a VM configuration file; for example `debian-bullseye.conf` |
||||||
|
|
||||||
|
``` {.bash} |
||||||
|
guest_os="linux" |
||||||
|
disk_img="debian-bullseye/disk.qcow2" |
||||||
|
iso="debian-bullseye/firmware-11.0.0-amd64-DVD-1.iso" |
||||||
|
``` |
||||||
|
|
||||||
|
- Use `quickemu` to start the virtual machine: |
||||||
|
|
||||||
|
``` {.bash} |
||||||
|
quickemu --vm debian-bullseye.conf |
||||||
|
``` |
||||||
|
|
||||||
|
- Complete the installation as normal. |
||||||
|
- Post-install: |
||||||
|
- Install the SPICE agent (`spice-vdagent`) to enable copy/paste |
||||||
|
and USB redirection. |
||||||
|
- Install the SPICE WebDAV agent (`spice-webdavd`) to enable file |
||||||
|
sharing. |
||||||
|
|
||||||
|
macOS Guest |
||||||
|
----------- |
||||||
|
|
||||||
|
`quickget` automatically downloads a macOS recovery image and creates a |
||||||
|
virtual machine configuration. |
||||||
|
|
||||||
|
``` {.bash} |
||||||
|
quickget macos catalina |
||||||
|
quickemu --vm macos-catalina.conf |
||||||
|
``` |
||||||
|
|
||||||
|
macOS `high-sierra`, `mojave`, `catalina`, `big-sur` and `monterey` are |
||||||
|
supported. |
||||||
|
|
||||||
|
- Use cursor keys and enter key to select the **macOS Base System** |
||||||
|
- From **macOS Utilities** |
||||||
|
- Click **Disk Utility** and **Continue** |
||||||
|
- On macOS Catalina, Big Sur & Monterey |
||||||
|
- Select `Apple Inc. VirtIO Block Media` from the list and |
||||||
|
click **Erase**. |
||||||
|
- On macOS Mojave and High Sierra |
||||||
|
- Select `QEMU HARDDISK Media` (\~103.08GB) from the list |
||||||
|
and click **Erase**. |
||||||
|
- Enter a `Name:` for the disk and click **Erase**. |
||||||
|
- Click **Done**. |
||||||
|
- Close Disk Utility |
||||||
|
- From **macOS Utilities** |
||||||
|
- Click **Reinstall macOS** and **Continue** |
||||||
|
- Complete the installation as you normally would. |
||||||
|
- On the first reboot use cursor keys and enter key to select |
||||||
|
**macOS Installer** |
||||||
|
- On the subsequent reboots use cursor keys and enter key to |
||||||
|
select the disk you named |
||||||
|
|
||||||
|
The default macOS configuration looks like this: |
||||||
|
|
||||||
|
``` {.bash} |
||||||
|
guest_os="macos" |
||||||
|
img="macos-catalina/RecoveryImage.img" |
||||||
|
disk_img="macos-catalina/disk.qcow2" |
||||||
|
macos_release="catalina" |
||||||
|
``` |
||||||
|
|
||||||
|
- `guest_os="macos"` instructs Quickemu to optimise for macOS. |
||||||
|
- `macos_release="catalina"` instructs Quickemu to optimise for a |
||||||
|
particular macOS release. |
||||||
|
- For example VirtIO Network and Memory Ballooning are available |
||||||
|
in Big Sur and newer, but not previous releases. |
||||||
|
- And VirtIO Block Media (disks) are supported/stable in Catalina |
||||||
|
and newer. |
||||||
|
|
||||||
|
### macOS compatibility |
||||||
|
|
||||||
|
There are some considerations when running macOS via Quickemu. |
||||||
|
|
||||||
|
- Supported macOS releases: |
||||||
|
- High Sierra |
||||||
|
- Mojave |
||||||
|
- Catalina **(Recommended)** |
||||||
|
- Big Sur |
||||||
|
- Monterey |
||||||
|
- `quickemu` will automatically download the required |
||||||
|
[OpenCore](https://github.com/acidanthera/OpenCorePkg) bootloader |
||||||
|
and OVMF firmware from [OSX-KVM](https://github.com/kholia/OSX-KVM). |
||||||
|
- Optimised by default, but no GPU acceleration is available. |
||||||
|
- Host CPU vendor is detected and guest CPU is optimised |
||||||
|
accordingly. |
||||||
|
- [VirtIO Block |
||||||
|
Media](https://www.kraxel.org/blog/2019/06/macos-qemu-guest/) is |
||||||
|
used for the system disk where supported. |
||||||
|
- [VirtIO `usb-tablet`](http://philjordan.eu/osx-virt/) is used |
||||||
|
for the mouse. |
||||||
|
- VirtIO Network (`virtio-net`) is supported and enabled on macOS |
||||||
|
Big Sur and newer but previous releases use `vmxnet3`. |
||||||
|
- VirtIO Memory Ballooning is supported and enabled on macOS Big |
||||||
|
Sur and newer but disabled for other support macOS releases. |
||||||
|
- USB host and SPICE pass-through is: |
||||||
|
- UHCI (USB 2.0) on macOS Catalina and earlier. |
||||||
|
- XHCI (USB 3.0) on macOS Big Sur and newer. |
||||||
|
- Display resolution can only be changed via macOS System Preferences. |
||||||
|
- Full Duplex audio works on macOS High Sierra, Mojave and Catalina. |
||||||
|
- **macOS Big Sur and Monterey have no audio at all**. |
||||||
|
- 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). |
||||||
|
- Copy/paste via SPICE agent is **not available on macOS**. |
||||||
|
|
||||||
|
Windows 8.1, 10 & 11 Guests |
||||||
|
--------------------------- |
||||||
|
|
||||||
|
`quickget` 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. |
||||||
|
|
||||||
|
``` {.bash} |
||||||
|
quickget windows 11 |
||||||
|
quickemu --vm windows-11.conf |
||||||
|
``` |
||||||
|
|
||||||
|
- Complete the installation as you normally would. |
||||||
|
- All relevant drivers and services should be installed automatically. |
||||||
|
|
||||||
|
### Regional versions |
||||||
|
|
||||||
|
By default `quickget` will download the *"English International"* |
||||||
|
release, but you can optionally specify one of the supported languages: |
||||||
|
For example: |
||||||
|
|
||||||
|
``` {.bash} |
||||||
|
quickget windows 11 "Chinese (Traditional)" |
||||||
|
``` |
||||||
|
|
||||||
|
The default Windows 11 configuration looks like this: |
||||||
|
|
||||||
|
``` {.bash} |
||||||
|
guest_os="windows" |
||||||
|
disk_img="windows-11/disk.qcow2" |
||||||
|
iso="windows-11/Win11_EnglishInternational_x64.iso" |
||||||
|
fixed_iso="windows-11/virtio-win.iso" |
||||||
|
tpm="on" |
||||||
|
``` |
||||||
|
|
||||||
|
- `guest_os="windows"` instructs `quickemu` to optimise for Windows. |
||||||
|
- `fixed_iso=` specifies the ISO image that provides VirtIO drivers. |
||||||
|
- `tpm="on"` instructs `quickemu` to create a software emulated TPM |
||||||
|
device using `swtpm`. |
||||||
|
|
||||||
|
All the options |
||||||
|
=============== |
||||||
|
|
||||||
|
Here are the usage instructions: |
||||||
|
|
||||||
|
``` {.bash} |
||||||
|
|
||||||
|
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's configuration |
||||||
|
--display : Select display backend. 'sdl' (default), 'gtk', 'none', or 'spice' |
||||||
|
--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 |
||||||
|
|
||||||
|
``` |
||||||
|
|
||||||
|
Desktop shortcuts |
||||||
|
----------------- |
||||||
|
|
||||||
|
Desktop shortcuts can be created for a VM, the shortcuts are saved in |
||||||
|
`~/.local/share/applications`. Here is an example of how to create a |
||||||
|
shortcut. |
||||||
|
|
||||||
|
``` {.bash} |
||||||
|
quickemu --vm ubuntu-20.04-desktop.conf --shortcut |
||||||
|
``` |
||||||
|
|
||||||
|
Screen and window size (Linux guests only) |
||||||
|
------------------------------------------ |
||||||
|
|
||||||
|
`qemu` will always default to the primary monitor to display the VM's |
||||||
|
window. |
||||||
|
|
||||||
|
Without the `--screen` option, `quickemu` will look for the size of the |
||||||
|
smallest monitor, and use a size that fits on said monitor. |
||||||
|
|
||||||
|
The `--screen` option forces `quickemu` to use the size of the given |
||||||
|
monitor to compute the size of the window. **It won't use that monitor |
||||||
|
to display the VM's window if it's not the primary monitor**. This is |
||||||
|
useful if the primary monitor if not the smallest one, and if the VM's |
||||||
|
window doesn't need to be moved around. |
||||||
|
|
||||||
|
The `--screen` option is also useful with the `--fullscreen` option, |
||||||
|
again because `qemu` will always use the primary monitor. In order for |
||||||
|
the fullscreen mode to work properly, the resolution of the VM's window |
||||||
|
must match the resolution of the screen. |
||||||
|
|
||||||
|
To know which screen to use, type: |
||||||
|
|
||||||
|
``` {.bash} |
||||||
|
xrandr --listmonitors | grep -v Monitors |
||||||
|
``` |
||||||
|
|
||||||
|
The command will output something like this: |
||||||
|
|
||||||
|
``` {.bash} |
||||||
|
0: +*HDMI-0 2560/597x1440/336+1920+0 HDMI-0 |
||||||
|
1: +DVI-D-0 1920/527x1080/296+0+0 DVI-D-0 |
||||||
|
``` |
||||||
|
|
||||||
|
The first number is what needs to be passed to the `--screen` option. |
||||||
|
|
||||||
|
For example: |
||||||
|
|
||||||
|
``` {.bash} |
||||||
|
quickemu --vm vm.conf --screen 0 |
||||||
|
``` |
||||||
|
|
||||||
|
The above uses the 2560x1440 screen to compute the size of the window, |
||||||
|
which Quickemu sizes to 2048x1152. Without the `--screen` option, |
||||||
|
Quickemu would have used the 1920x1080 monitor which results in a window |
||||||
|
size of 1664x936. |
||||||
|
|
||||||
|
References |
||||||
|
========== |
||||||
|
|
||||||
|
Useful reference that assisted the development of Quickemu. |
||||||
|
|
||||||
|
- General |
||||||
|
- [QEMU's documentation!](https://qemu.readthedocs.io/en/latest/) |
||||||
|
- <https://pve.proxmox.com/wiki/Qemu/KVM_Virtual_Machines> |
||||||
|
- <https://www.kraxel.org/blog/2020/01/qemu-sound-audiodev/> |
||||||
|
- macOS |
||||||
|
- <https://www.nicksherlock.com/2020/06/installing-macos-big-sur-on-proxmox/> |
||||||
|
- <https://passthroughpo.st/mac-os-adds-early-support-for-virtio-qemu/> |
||||||
|
- <https://github.com/kholia/OSX-KVM> |
||||||
|
- <https://github.com/thenickdude/KVM-Opencore> |
||||||
|
- <https://github.com/acidanthera/OpenCorePkg/tree/master/Utilities/macrecovery> |
||||||
|
- <https://www.kraxel.org/blog/2017/09/running-macos-as-guest-in-kvm/> |
||||||
|
- <https://www.nicksherlock.com/2017/10/passthrough-of-advanced-cpu-features-for-macos-high-sierra-guests/> |
||||||
|
- <http://philjordan.eu/osx-virt/> |
||||||
|
- <https://github.com/Dids/clover-builder> |
||||||
|
- [OpenCore |
||||||
|
Configurator](https://mackie100projects.altervista.org) |
||||||
|
- Windows |
||||||
|
- <https://www.heiko-sieger.info/running-windows-10-on-linux-using-kvm-with-vga-passthrough/> |
||||||
|
- <https://leduccc.medium.com/improving-the-performance-of-a-windows-10-guest-on-qemu-a5b3f54d9cf5> |
||||||
|
- <https://frontpagelinux.com/tutorials/how-to-use-linux-kvm-to-optimize-your-windows-10-virtual-machine/> |
||||||
|
- <https://turlucode.com/qemu-command-line-args/> |
||||||
|
- <https://github.com/pbatard/Fido> |
||||||
|
- <https://www.catapultsystems.com/blogs/create-zero-touch-windows-10-iso/> |
||||||
|
- TPM |
||||||
|
- <https://qemu-project.gitlab.io/qemu/specs/tpm.html> |
||||||
|
- <https://www.tecklyfe.com/how-to-create-a-windows-11-virtual-machine-in-qemu/> |
||||||
|
- 9p & virtiofs |
||||||
|
- <https://wiki.qemu.org/Documentation/9p> |
||||||
|
- <https://wiki.qemu.org/Documentation/9psetup> |
||||||
|
- <https://www.kraxel.org/blog/2019/06/macos-qemu-guest/> |
||||||
|
- <https://superuser.com/questions/628169/how-to-share-a-directory-with-the-host-without-networking-in-qemu> |
||||||
|
- <https://virtio-fs.gitlab.io/> |
||||||
|
|
||||||
|
AUTHORS |
||||||
|
======= |
||||||
|
|
||||||
|
Written by Martin Wimpress. |
||||||
|
|
||||||
|
BUGS |
||||||
|
==== |
||||||
|
|
||||||
|
Submit bug reports online at: |
||||||
|
<https://github.com/quickemu-project/quickemu/issues> |
||||||
|
|
||||||
|
SEE ALSO |
||||||
|
======== |
||||||
|
|
||||||
|
Full sources at: <https://github.com/quickemu-project/quickemu> |
||||||
|
|
||||||
|
quickemu\_conf(1), quickget(1), quickgui(1) |
@ -0,0 +1,249 @@ |
|||||||
|
.\" Automatically generated by Pandoc 2.9.2.1 |
||||||
|
.\" |
||||||
|
.TH "QUICKEMU_CONF" "1" "February 20, 2022" "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] |
||||||
|
bridge=\[dq]\[dq] |
||||||
|
cpu_cores=\[dq]\[dq] |
||||||
|
disk_img=\[dq]\[dq] |
||||||
|
disk_size=\[dq]\[dq] |
||||||
|
fixed_iso=\[dq]\[dq] |
||||||
|
floppy=\[dq]\[dq] |
||||||
|
guest_os=\[dq]linux\[dq] |
||||||
|
img=\[dq]\[dq] |
||||||
|
iso=\[dq]\[dq] |
||||||
|
macos_release=\[dq]\[dq] |
||||||
|
port_forwards=() |
||||||
|
preallocation=\[dq]off\[dq] |
||||||
|
ram=\[dq]\[dq] |
||||||
|
secureboot=\[dq]off\[dq] |
||||||
|
tpm=\[dq]off\[dq] |
||||||
|
usb_devices=() |
||||||
|
\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[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 |
||||||
|
.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 BIOS and EFI |
||||||
|
.PP |
||||||
|
Since Quickemu 2.1.0 \f[C]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[C]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[C]cpu_cores=\[dq]4\[dq]\f[R] - Specify the number of CPU cores |
||||||
|
allocated to the VM |
||||||
|
.IP \[bu] 2 |
||||||
|
\f[C]ram=\[dq]4G\[dq]\f[R] - Specify the amount of RAM to allocate to |
||||||
|
the VM |
||||||
|
.IP \[bu] 2 |
||||||
|
\f[C]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[C]off\f[R] (default), |
||||||
|
\f[C]metadata\f[R], \f[C]falloc\f[R], \f[C]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[C]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[C]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[C]floppy=\[dq]/path/to/floppy.img\[dq]\f[R] |
||||||
|
.SH File Sharing |
||||||
|
.PP |
||||||
|
All File Sharing options will only expose \f[C]\[ti]/Public\f[R] (or |
||||||
|
localised variations) for the current user to the guest VMs. |
||||||
|
.SS Samba \[u1F427] \[u1F34F] \[u1FA9F] |
||||||
|
.PP |
||||||
|
If \f[C]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 |
||||||
|
.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[C]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 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[C]bridge=\[dq]br0\[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[C]--display spice\f[R] |
||||||
|
and then select \f[C]Input\f[R] -> |
||||||
|
\f[C]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[C]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[C]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[C]tpm=\[dq]on\[dq]\f[R] to your VM configuration. |
||||||
|
\f[C]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. |
@ -0,0 +1,262 @@ |
|||||||
|
--- |
||||||
|
author: Martin Wimpress |
||||||
|
date: 'February 20, 2022' |
||||||
|
footer: quickemu\_conf |
||||||
|
header: Quickemu Configuration Manual |
||||||
|
section: 1 |
||||||
|
title: QUICKEMU\_CONF |
||||||
|
--- |
||||||
|
|
||||||
|
NAME |
||||||
|
==== |
||||||
|
|
||||||
|
quickemu\_conf - Options and parameters in the quickemu \<vm\>.conf |
||||||
|
|
||||||
|
DESCRIPTION |
||||||
|
=========== |
||||||
|
|
||||||
|
**quickemu** 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 |
||||||
|
|
||||||
|
OPTIONS |
||||||
|
======= |
||||||
|
|
||||||
|
These are the options and defaults for the \<vm\>.conf file |
||||||
|
|
||||||
|
``` {.bash} |
||||||
|
# Lowercase variables are used in the VM config file only |
||||||
|
boot="efi" |
||||||
|
bridge="" |
||||||
|
cpu_cores="" |
||||||
|
disk_img="" |
||||||
|
disk_size="" |
||||||
|
fixed_iso="" |
||||||
|
floppy="" |
||||||
|
guest_os="linux" |
||||||
|
img="" |
||||||
|
iso="" |
||||||
|
macos_release="" |
||||||
|
port_forwards=() |
||||||
|
preallocation="off" |
||||||
|
ram="" |
||||||
|
secureboot="off" |
||||||
|
tpm="off" |
||||||
|
usb_devices=() |
||||||
|
``` |
||||||
|
|
||||||
|
EXAMPLES |
||||||
|
======== |
||||||
|
|
||||||
|
``` {.bash} |
||||||
|
guest_os="linux" |
||||||
|
disk_img="debian-bullseye/disk.qcow2" |
||||||
|
iso="debian-bullseye/firmware-11.0.0-amd64-DVD-1.iso" |
||||||
|
``` |
||||||
|
|
||||||
|
The default macOS configuration looks like this: |
||||||
|
|
||||||
|
``` {.bash} |
||||||
|
guest_os="macos" |
||||||
|
img="macos-catalina/RecoveryImage.img" |
||||||
|
disk_img="macos-catalina/disk.qcow2" |
||||||
|
macos_release="catalina" |
||||||
|
``` |
||||||
|
|
||||||
|
- `guest_os="macos"` instructs Quickemu to optimise for macOS. |
||||||
|
- `macos_release="catalina"` instructs Quickemu to optimise for a |
||||||
|
particular macOS release. |
||||||
|
- For example VirtIO Network and Memory Ballooning are available |
||||||
|
in Big Sur and newer, but not previous releases. |
||||||
|
- And VirtIO Block Media (disks) are supported/stable in Catalina |
||||||
|
and newer. |
||||||
|
|
||||||
|
The default Windows 11 configuration looks like this: |
||||||
|
|
||||||
|
``` {.bash} |
||||||
|
guest_os="windows" |
||||||
|
disk_img="windows-11/disk.qcow2" |
||||||
|
iso="windows-11/Win11_EnglishInternational_x64.iso" |
||||||
|
fixed_iso="windows-11/virtio-win.iso" |
||||||
|
tpm="on" |
||||||
|
``` |
||||||
|
|
||||||
|
- `guest_os="windows"` instructs `quickemu` to optimise for Windows. |
||||||
|
- `fixed_iso=` specifies the ISO image that provides VirtIO drivers. |
||||||
|
- `tpm="on"` instructs `quickemu` to create a software emulated TPM |
||||||
|
device using `swtpm`. |
||||||
|
|
||||||
|
BIOS and EFI |
||||||
|
============ |
||||||
|
|
||||||
|
Since Quickemu 2.1.0 `efi` 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. |
||||||
|
|
||||||
|
- `boot="legacy"` - Enable Legacy BIOS boot |
||||||
|
|
||||||
|
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. |
||||||
|
|
||||||
|
Add additional lines to your virtual machine configuration: |
||||||
|
|
||||||
|
- `cpu_cores="4"` - Specify the number of CPU cores allocated to the |
||||||
|
VM |
||||||
|
- `ram="4G"` - Specify the amount of RAM to allocate to the VM |
||||||
|
- `disk_size="16G"` - Specify the size of the virtual disk allocated |
||||||
|
to the VM |
||||||
|
|
||||||
|
Disk preallocation |
||||||
|
------------------ |
||||||
|
|
||||||
|
Preallocation mode (allowed values: `off` (default), `metadata`, |
||||||
|
`falloc`, `full`). An image with preallocated metadata is initially |
||||||
|
larger but can improve performance when the image needs to grow. |
||||||
|
|
||||||
|
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. |
||||||
|
|
||||||
|
- `preallocation="metadata"` |
||||||
|
|
||||||
|
CD-ROM disks |
||||||
|
------------ |
||||||
|
|
||||||
|
If you want to expose an ISO image from the host to guest add the |
||||||
|
following line to the VM configuration: |
||||||
|
|
||||||
|
- `fixed_iso="/path/to/image.iso"` |
||||||
|
|
||||||
|
Floppy disks |
||||||
|
------------ |
||||||
|
|
||||||
|
If you're like [Alan Pope](https://popey.com) you'll probably want to |
||||||
|
mount a floppy disk image in the guest. To do so add the following line |
||||||
|
to the VM configuration: |
||||||
|
|
||||||
|
- `floppy="/path/to/floppy.img"` |
||||||
|
|
||||||
|
File Sharing |
||||||
|
============ |
||||||
|
|
||||||
|
All File Sharing options will only expose `~/Public` (or localised |
||||||
|
variations) for the current user to the guest VMs. |
||||||
|
|
||||||
|
Samba 🐧 🍏 🪟 |
||||||
|
----------- |
||||||
|
|
||||||
|
If `smbd` 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. |
||||||
|
|
||||||
|
You can install the minimal Samba components on Ubuntu using: |
||||||
|
|
||||||
|
``` {.bash} |
||||||
|
sudo apt install --no-install-recommends samba |
||||||
|
``` |
||||||
|
|
||||||
|
SPICE WebDAV 🐧 🪟 |
||||||
|
---------------- |
||||||
|
|
||||||
|
- TBD |
||||||
|
|
||||||
|
VirtIO-9P 🐧 🍏 |
||||||
|
------------- |
||||||
|
|
||||||
|
- TBD |
||||||
|
|
||||||
|
Network port forwarding |
||||||
|
======================= |
||||||
|
|
||||||
|
Add an additional line to your virtual machine configuration. For |
||||||
|
example: |
||||||
|
|
||||||
|
- `port_forwards=("8123:8123" "8888:80")` |
||||||
|
|
||||||
|
In the example above: |
||||||
|
|
||||||
|
- Port 8123 on the host is forwarded to port 8123 on the guest. |
||||||
|
- Port 8888 on the host is forwarded to port 80 on the guest. |
||||||
|
|
||||||
|
Bridged networking |
||||||
|
================== |
||||||
|
|
||||||
|
Connect your virtual machine to a preconfigured network bridge. Add an |
||||||
|
additional line to your virtual machine configuration |
||||||
|
|
||||||
|
- `bridge="br0"` |
||||||
|
|
||||||
|
USB redirection |
||||||
|
=============== |
||||||
|
|
||||||
|
Quickemu supports USB redirection via SPICE pass-through and host |
||||||
|
pass-through. |
||||||
|
|
||||||
|
SPICE redirection (recommended) |
||||||
|
------------------------------- |
||||||
|
|
||||||
|
Using SPICE for USB pass-through is easiest as it doesn't require any |
||||||
|
elevated permission, start Quickemu with `--display spice` and then |
||||||
|
select `Input` -\> `Select USB Device for redirection` from the menu to |
||||||
|
choose which device(s) you want to attach to the guest. |
||||||
|
|
||||||
|
Host redirection **NOT Recommended** |
||||||
|
------------------------------------ |
||||||
|
|
||||||
|
**USB host redirection is not recommended**, it is provided purely for |
||||||
|
backwards compatibility to older versions of Quickemu. Using SPICE is |
||||||
|
preferred, see above. |
||||||
|
|
||||||
|
Add an additional line to your virtual machine configuration. For |
||||||
|
example: |
||||||
|
|
||||||
|
- `usb_devices=("046d:082d" "046d:085e")` |
||||||
|
|
||||||
|
In the example above: |
||||||
|
|
||||||
|
- The USB device with vendor\_id 046d and product\_id 082d will be |
||||||
|
exposed to the guest. |
||||||
|
- The USB device with vendor\_id 046d and product\_id 085e will be |
||||||
|
exposed to the guest. |
||||||
|
|
||||||
|
If the USB devices are not writable, `quickemu` will display the |
||||||
|
appropriate commands to modify the USB device(s) access permissions, |
||||||
|
like this: |
||||||
|
|
||||||
|
- 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 👆 |
||||||
|
|
||||||
|
TPM |
||||||
|
=== |
||||||
|
|
||||||
|
Since Quickemu 2.2.0 a software emulated TPM device can be added to |
||||||
|
guest virtual machines. Just add `tpm="on"` to your VM configuration. |
||||||
|
`quickget` will automatically add this line to Windows 11 virtual |
||||||
|
machines. |
||||||
|
|
||||||
|
AUTHORS |
||||||
|
======= |
||||||
|
|
||||||
|
Written by Martin Wimpress. |
||||||
|
|
||||||
|
BUGS |
||||||
|
==== |
||||||
|
|
||||||
|
Submit bug reports online at: |
||||||
|
<https://github.com/quickemu-project/quickemu/issues> |
||||||
|
|
||||||
|
SEE ALSO |
||||||
|
======== |
||||||
|
|
||||||
|
Full sources at: <https://github.com/quickemu-project/quickemu> |
||||||
|
|
||||||
|
quickget(1), quickemu(1), quickgui(1) |
@ -0,0 +1,418 @@ |
|||||||
|
.\" Automatically generated by Pandoc 2.9.2.1 |
||||||
|
.\" |
||||||
|
.TH "QUICKGET" "1" "February 20, 2022" "quickget" "Quickget User Manual" |
||||||
|
.hy |
||||||
|
.SH NAME |
||||||
|
.PP |
||||||
|
quickget - download and prepare materials for building a quickemu VM |
||||||
|
.SH SYNOPSIS |
||||||
|
.PP |
||||||
|
\f[B]quickget\f[R] [\f[I]os\f[R]] [\f[I]release\f[R]] |
||||||
|
[\f[I]edition\f[R]] | [\f[I]OPTION\f[R]]* |
||||||
|
.SH DESCRIPTION |
||||||
|
.PP |
||||||
|
\f[B]quickget\f[R] will download the requisite materials and prepare a |
||||||
|
configuration for \f[C]quickemu\f[R] to use to build and run |
||||||
|
.SH OPTIONS |
||||||
|
.TP |
||||||
|
\f[B]version | -version | \[en]version\f[R] |
||||||
|
show version (from Quickemu) |
||||||
|
.TP |
||||||
|
\f[B]list | list_csv | list_json\f[R] |
||||||
|
provide a csv list of all supported guest OSes, versions and variants. |
||||||
|
.TP |
||||||
|
\f[B][OS] [Release] [Edition]\f[R] |
||||||
|
specify the OS and release (and optional edition) if insufficient input |
||||||
|
is provided a list of missing options will be reported and the script |
||||||
|
will exit. |
||||||
|
Editions may not apply and will be defaulted if not provided. |
||||||
|
.SH NOTES |
||||||
|
.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 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(1), quickemu_conf(1), quickgui(1) |
||||||
|
.SH AUTHORS |
||||||
|
Martin Wimpress. |
@ -0,0 +1,307 @@ |
|||||||
|
--- |
||||||
|
author: Martin Wimpress |
||||||
|
date: 'February 20, 2022' |
||||||
|
footer: quickget |
||||||
|
header: Quickget User Manual |
||||||
|
section: 1 |
||||||
|
title: QUICKGET |
||||||
|
--- |
||||||
|
|
||||||
|
NAME |
||||||
|
==== |
||||||
|
|
||||||
|
quickget - download and prepare materials for building a quickemu VM |
||||||
|
|
||||||
|
SYNOPSIS |
||||||
|
======== |
||||||
|
|
||||||
|
**quickget** \[*os*\] \[*release*\] \[*edition*\] \| \[*OPTION*\]\* |
||||||
|
|
||||||
|
DESCRIPTION |
||||||
|
=========== |
||||||
|
|
||||||
|
**quickget** will download the requisite materials and prepare a |
||||||
|
configuration for `quickemu` to use to build and run |
||||||
|
|
||||||
|
OPTIONS |
||||||
|
======= |
||||||
|
|
||||||
|
**version \| -version \| --version** |
||||||
|
: show version (from Quickemu) |
||||||
|
|
||||||
|
**list \| list\_csv \| list\_json** |
||||||
|
: provide a csv list of all supported guest OSes, versions and |
||||||
|
variants. |
||||||
|
|
||||||
|
**\[OS\] \[Release\] \[Edition\]** |
||||||
|
: specify the OS and release (and optional edition) if insufficient |
||||||
|
input is provided a list of missing options will be reported and the |
||||||
|
script will exit. Editions may not apply and will be defaulted if |
||||||
|
not provided. |
||||||
|
|
||||||
|
NOTES |
||||||
|
===== |
||||||
|
|
||||||
|
Ubuntu Guest |
||||||
|
------------ |
||||||
|
|
||||||
|
`quickget` will automatically download an Ubuntu release and create the |
||||||
|
virtual machine configuration. |
||||||
|
|
||||||
|
``` {.bash} |
||||||
|
quickget ubuntu 20.04 |
||||||
|
quickemu --vm ubuntu-20.04.conf |
||||||
|
``` |
||||||
|
|
||||||
|
- Complete the installation as normal. |
||||||
|
- Post-install: |
||||||
|
- Install the SPICE agent (`spice-vdagent`) to enable copy/paste |
||||||
|
and USB redirection |
||||||
|
- `sudo apt install spice-vdagent` |
||||||
|
- Install the SPICE WebDAV agent (`spice-webdavd`) to enable file |
||||||
|
sharing. |
||||||
|
- `sudo apt install spice-webdavd` |
||||||
|
|
||||||
|
### Ubuntu devel (daily-live) images |
||||||
|
|
||||||
|
`quickget` can also download/refresh devel images via `zsync` for Ubuntu |
||||||
|
developers and testers. |
||||||
|
|
||||||
|
``` {.bash} |
||||||
|
quickget ubuntu devel |
||||||
|
quickemu --vm ubuntu-devel.conf |
||||||
|
``` |
||||||
|
|
||||||
|
You can run `quickget ubuntu devel` to refresh your daily development |
||||||
|
image as often as you like, it will even automatically switch to a new |
||||||
|
series. |
||||||
|
|
||||||
|
### Ubuntu Flavours |
||||||
|
|
||||||
|
All the official Ubuntu flavours are supported, just replace `ubuntu` |
||||||
|
with your preferred flavour. |
||||||
|
|
||||||
|
- `kubuntu` (Kubuntu) |
||||||
|
- `lubuntu` (Lubuntu) |
||||||
|
- `ubuntu-budgie` (Ubuntu Budgie) |
||||||
|
- `ubuntukylin` (Ubuntu Kylin) |
||||||
|
- `ubuntu-mate` (Ubuntu MATE) |
||||||
|
- `ubuntustudio` (Ubuntu Studio) |
||||||
|
- `ubuntu` (Ubuntu) |
||||||
|
- `xubuntu` (Xubuntu) |
||||||
|
|
||||||
|
Other Operating Systems |
||||||
|
----------------------- |
||||||
|
|
||||||
|
`quickget` also supports: |
||||||
|
|
||||||
|
- `alma` (Alma Linux) |
||||||
|
- `alpine` (Alpine Linux) |
||||||
|
- `android` (Android x86) |
||||||
|
- `archlinux` (Arch Linux) |
||||||
|
- `arcolinux` (Arco Linux) |
||||||
|
- `cachyos` (CachyOS) |
||||||
|
- `debian` (Debian) |
||||||
|
- `devuan` (Devuan) |
||||||
|
- `dragonflybsd` (DragonFlyBSD) |
||||||
|
- `elementary` (elementary OS) |
||||||
|
- `fedora` (Fedora) |
||||||
|
- `freebsd` (FreeBSD) |
||||||
|
- `garuda` (Garuda Linux) |
||||||
|
- `gentoo` (Gentoo) |
||||||
|
- `ghostbsd` (GhostBSD) |
||||||
|
- `haiku` (Haiku) |
||||||
|
- `kali` (Kali) |
||||||
|
- `kdeneon` (KDE Neon) |
||||||
|
- `kolibrios` (KolibriOS) |
||||||
|
- `linuxmint` (Linux Mint) |
||||||
|
- `manjaro` (Manjaro) |
||||||
|
- `mxlinux` (MX Linux) |
||||||
|
- `netboot` (netboot.xyz) |
||||||
|
- `netbsd` (NetBSD) |
||||||
|
- `nixos` (NixOS) |
||||||
|
- `openbsd` (OpenBSD) |
||||||
|
- `opensuse` (openSUSE) |
||||||
|
- `oraclelinux` (Oracle Linux) |
||||||
|
- `popos` (Pop!\_OS) |
||||||
|
- `regolith` (Regolith Linux) |
||||||
|
- `rockylinux` (Rocky Linux) |
||||||
|
- `slackware` (Slackware) |
||||||
|
- `solus` (Solus) |
||||||
|
- `tails` (Tails) |
||||||
|
- `void` (Void Linux) |
||||||
|
- `zorin` (Zorin OS) |
||||||
|
|
||||||
|
Or you can download a Linux image and manually create a VM |
||||||
|
configuration. |
||||||
|
|
||||||
|
- Download a .iso image of a Linux distribution |
||||||
|
- Create a VM configuration file; for example `debian-bullseye.conf` |
||||||
|
|
||||||
|
``` {.bash} |
||||||
|
guest_os="linux" |
||||||
|
disk_img="debian-bullseye/disk.qcow2" |
||||||
|
iso="debian-bullseye/firmware-11.0.0-amd64-DVD-1.iso" |
||||||
|
``` |
||||||
|
|
||||||
|
- Use `quickemu` to start the virtual machine: |
||||||
|
|
||||||
|
``` {.bash} |
||||||
|
quickemu --vm debian-bullseye.conf |
||||||
|
``` |
||||||
|
|
||||||
|
- Complete the installation as normal. |
||||||
|
- Post-install: |
||||||
|
- Install the SPICE agent (`spice-vdagent`) to enable copy/paste |
||||||
|
and USB redirection. |
||||||
|
- Install the SPICE WebDAV agent (`spice-webdavd`) to enable file |
||||||
|
sharing. |
||||||
|
|
||||||
|
macOS Guest |
||||||
|
----------- |
||||||
|
|
||||||
|
`quickget` automatically downloads a macOS recovery image and creates a |
||||||
|
virtual machine configuration. |
||||||
|
|
||||||
|
``` {.bash} |
||||||
|
quickget macos catalina |
||||||
|
quickemu --vm macos-catalina.conf |
||||||
|
``` |
||||||
|
|
||||||
|
macOS `high-sierra`, `mojave`, `catalina`, `big-sur` and `monterey` are |
||||||
|
supported. |
||||||
|
|
||||||
|
- Use cursor keys and enter key to select the **macOS Base System** |
||||||
|
- From **macOS Utilities** |
||||||
|
- Click **Disk Utility** and **Continue** |
||||||
|
- On macOS Catalina, Big Sur & Monterey |
||||||
|
- Select `Apple Inc. VirtIO Block Media` from the list and |
||||||
|
click **Erase**. |
||||||
|
- On macOS Mojave and High Sierra |
||||||
|
- Select `QEMU HARDDISK Media` (\~103.08GB) from the list |
||||||
|
and click **Erase**. |
||||||
|
- Enter a `Name:` for the disk and click **Erase**. |
||||||
|
- Click **Done**. |
||||||
|
- Close Disk Utility |
||||||
|
- From **macOS Utilities** |
||||||
|
- Click **Reinstall macOS** and **Continue** |
||||||
|
- Complete the installation as you normally would. |
||||||
|
- On the first reboot use cursor keys and enter key to select |
||||||
|
**macOS Installer** |
||||||
|
- On the subsequent reboots use cursor keys and enter key to |
||||||
|
select the disk you named |
||||||
|
|
||||||
|
The default macOS configuration looks like this: |
||||||
|
|
||||||
|
``` {.bash} |
||||||
|
guest_os="macos" |
||||||
|
img="macos-catalina/RecoveryImage.img" |
||||||
|
disk_img="macos-catalina/disk.qcow2" |
||||||
|
macos_release="catalina" |
||||||
|
``` |
||||||
|
|
||||||
|
- `guest_os="macos"` instructs Quickemu to optimise for macOS. |
||||||
|
- `macos_release="catalina"` instructs Quickemu to optimise for a |
||||||
|
particular macOS release. |
||||||
|
- For example VirtIO Network and Memory Ballooning are available |
||||||
|
in Big Sur and newer, but not previous releases. |
||||||
|
- And VirtIO Block Media (disks) are supported/stable in Catalina |
||||||
|
and newer. |
||||||
|
|
||||||
|
### macOS compatibility |
||||||
|
|
||||||
|
There are some considerations when running macOS via Quickemu. |
||||||
|
|
||||||
|
- Supported macOS releases: |
||||||
|
- High Sierra |
||||||
|
- Mojave |
||||||
|
- Catalina **(Recommended)** |
||||||
|
- Big Sur |
||||||
|
- Monterey |
||||||
|
- `quickemu` will automatically download the required |
||||||
|
[OpenCore](https://github.com/acidanthera/OpenCorePkg) bootloader |
||||||
|
and OVMF firmware from [OSX-KVM](https://github.com/kholia/OSX-KVM). |
||||||
|
- Optimised by default, but no GPU acceleration is available. |
||||||
|
- Host CPU vendor is detected and guest CPU is optimised |
||||||
|
accordingly. |
||||||
|
- [VirtIO Block |
||||||
|
Media](https://www.kraxel.org/blog/2019/06/macos-qemu-guest/) is |
||||||
|
used for the system disk where supported. |
||||||
|
- [VirtIO `usb-tablet`](http://philjordan.eu/osx-virt/) is used |
||||||
|
for the mouse. |
||||||
|
- VirtIO Network (`virtio-net`) is supported and enabled on macOS |
||||||
|
Big Sur and newer but previous releases use `vmxnet3`. |
||||||
|
- VirtIO Memory Ballooning is supported and enabled on macOS Big |
||||||
|
Sur and newer but disabled for other support macOS releases. |
||||||
|
- USB host and SPICE pass-through is: |
||||||
|
- UHCI (USB 2.0) on macOS Catalina and earlier. |
||||||
|
- XHCI (USB 3.0) on macOS Big Sur and newer. |
||||||
|
- Display resolution can only be changed via macOS System Preferences. |
||||||
|
- Full Duplex audio works on macOS High Sierra, Mojave and Catalina. |
||||||
|
- **macOS Big Sur and Monterey have no audio at all**. |
||||||
|
- 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). |
||||||
|
- Copy/paste via SPICE agent is **not available on macOS**. |
||||||
|
|
||||||
|
Windows 8.1, 10 & 11 Guests |
||||||
|
--------------------------- |
||||||
|
|
||||||
|
`quickget` 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. |
||||||
|
|
||||||
|
``` {.bash} |
||||||
|
quickget windows 11 |
||||||
|
quickemu --vm windows-11.conf |
||||||
|
``` |
||||||
|
|
||||||
|
- Complete the installation as you normally would. |
||||||
|
- All relevant drivers and services should be installed automatically. |
||||||
|
|
||||||
|
### Regional versions |
||||||
|
|
||||||
|
By default `quickget` will download the *"English International"* |
||||||
|
release, but you can optionally specify one of the supported languages: |
||||||
|
For example: |
||||||
|
|
||||||
|
``` {.bash} |
||||||
|
quickget windows 11 "Chinese (Traditional)" |
||||||
|
``` |
||||||
|
|
||||||
|
The default Windows 11 configuration looks like this: |
||||||
|
|
||||||
|
``` {.bash} |
||||||
|
guest_os="windows" |
||||||
|
disk_img="windows-11/disk.qcow2" |
||||||
|
iso="windows-11/Win11_EnglishInternational_x64.iso" |
||||||
|
fixed_iso="windows-11/virtio-win.iso" |
||||||
|
tpm="on" |
||||||
|
``` |
||||||
|
|
||||||
|
- `guest_os="windows"` instructs `quickemu` to optimise for Windows. |
||||||
|
- `fixed_iso=` specifies the ISO image that provides VirtIO drivers. |
||||||
|
- `tpm="on"` instructs `quickemu` to create a software emulated TPM |
||||||
|
device using `swtpm`. |
||||||
|
|
||||||
|
AUTHORS |
||||||
|
======= |
||||||
|
|
||||||
|
Written by Martin Wimpress. |
||||||
|
|
||||||
|
BUGS |
||||||
|
==== |
||||||
|
|
||||||
|
Submit bug reports online at: |
||||||
|
<https://github.com/quickemu-project/quickemu/issues> |
||||||
|
|
||||||
|
SEE ALSO |
||||||
|
======== |
||||||
|
|
||||||
|
Full sources at: <https://github.com/quickemu-project/quickemu> |
||||||
|
|
||||||
|
quickemu(1), quickemu\_conf(1), quickgui(1) |
Loading…
Reference in new issue