quickemu/docs/quickget.1

.\" Automatically generated by Pandoc 2.19.2
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "QUICKGET" "1" "September 22, 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[V]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[V]quickget\f[R] will automatically download an Ubuntu release and
create the virtual machine configuration.
.IP
.nf
\f[C]
quickget ubuntu 22.04
quickemu --vm ubuntu-22.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[V]spice-vdagent\f[R]) in the guest to enable
copy/paste and USB redirection
.RS 2
.IP \[bu] 2
\f[V]sudo apt install spice-vdagent\f[R]
.RE
.IP \[bu] 2
Install the SPICE WebDAV agent (\f[V]spice-webdavd\f[R]) in the guest to
enable file sharing.
.RS 2
.IP \[bu] 2
\f[V]sudo apt install spice-webdavd\f[R]
.RE
.RE
.SS Ubuntu devel (daily-live) images
.PP
\f[V]quickget\f[R] can also download/refresh devel images via
\f[V]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[V]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[V]ubuntu\f[R] with your preferred flavour.
.IP \[bu] 2
\f[V]kubuntu\f[R] (Kubuntu)
.IP \[bu] 2
\f[V]lubuntu\f[R] (Lubuntu)
.IP \[bu] 2
\f[V]ubuntu-budgie\f[R] (Ubuntu Budgie)
.IP \[bu] 2
\f[V]ubuntukylin\f[R] (Ubuntu Kylin)
.IP \[bu] 2
\f[V]ubuntu-mate\f[R] (Ubuntu MATE)
.IP \[bu] 2
\f[V]ubuntustudio\f[R] (Ubuntu Studio)
.IP \[bu] 2
\f[V]ubuntu\f[R] (Ubuntu)
.IP \[bu] 2
\f[V]xubuntu\f[R] (Xubuntu)
.SS Other Operating Systems
.PP
\f[V]quickget\f[R] also supports:
.IP \[bu] 2
\f[V]alma\f[R] (Alma Linux)
.IP \[bu] 2
\f[V]alpine\f[R] (Alpine Linux)
.IP \[bu] 2
\f[V]android\f[R] (Android x86)
.IP \[bu] 2
\f[V]archlinux\f[R] (Arch Linux)
.IP \[bu] 2
\f[V]arcolinux\f[R] (Arco Linux)
.IP \[bu] 2
\f[V]batocera\f[R] (Batocera)
.IP \[bu] 2
\f[V]cachyos\f[R] (CachyOS)
.IP \[bu] 2
\f[V]centos-stream\f[R] (CentOS Stream)
.IP \[bu] 2
\f[V]debian\f[R] (Debian)
.IP \[bu] 2
\f[V]deepin\f[R] (Deepin)
.IP \[bu] 2
\f[V]devuan\f[R] (Devuan)
.IP \[bu] 2
\f[V]dragonflybsd\f[R] (DragonFlyBSD)
.IP \[bu] 2
\f[V]elementary\f[R] (elementary OS)
.IP \[bu] 2
\f[V]endeavouros\f[R] (EndeavourOS)
.IP \[bu] 2
\f[V]fedora\f[R] (Fedora)
.IP \[bu] 2
\f[V]freebsd\f[R] (FreeBSD)
.IP \[bu] 2
\f[V]freedos\f[R] (FreeDOS)
.IP \[bu] 2
\f[V]garuda\f[R] (Garuda Linux)
.IP \[bu] 2
\f[V]gentoo\f[R] (Gentoo)
.IP \[bu] 2
\f[V]ghostbsd\f[R] (GhostBSD)
.IP \[bu] 2
\f[V]haiku\f[R] (Haiku)
.IP \[bu] 2
\f[V]kali\f[R] (Kali)
.IP \[bu] 2
\f[V]kdeneon\f[R] (KDE Neon)
.IP \[bu] 2
\f[V]kolibrios\f[R] (KolibriOS)
.IP \[bu] 2
\f[V]linuxmint\f[R] (Linux Mint)
.IP \[bu] 2
\f[V]lmde\f[R] (Linux Mint Debian Edition)
.IP \[bu] 2
\f[V]manjaro\f[R] (Manjaro)
.IP \[bu] 2
\f[V]mxlinux\f[R] (MX Linux)
.IP \[bu] 2
\f[V]netboot\f[R] (netboot.xyz)
.IP \[bu] 2
\f[V]netbsd\f[R] (NetBSD)
.IP \[bu] 2
\f[V]nixos\f[R] (NixOS)
.IP \[bu] 2
\f[V]openbsd\f[R] (OpenBSD)
.IP \[bu] 2
\f[V]opensuse\f[R] (openSUSE)
.IP \[bu] 2
\f[V]oraclelinux\f[R] (Oracle Linux)
.IP \[bu] 2
\f[V]popos\f[R] (Pop!_OS)
.IP \[bu] 2
\f[V]reactos\f[R] (ReactOS)
.IP \[bu] 2
\f[V]rockylinux\f[R] (Rocky Linux)
.IP \[bu] 2
\f[V]slackware\f[R] (Slackware)
.IP \[bu] 2
\f[V]solus\f[R] (Solus)
.IP \[bu] 2
\f[V]tails\f[R] (Tails)
.IP \[bu] 2
\f[V]void\f[R] (Void Linux)
.IP \[bu] 2
\f[V]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[V]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[V]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[V]spice-vdagent\f[R]) in the guest to enable
copy/paste and USB redirection.
.IP \[bu] 2
Install the SPICE WebDAV agent (\f[V]spice-webdavd\f[R]) in the guest to
enable file sharing.
.RE
.SS macOS Guest
.PP
\f[V]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[V]high-sierra\f[R], \f[V]mojave\f[R], \f[V]catalina\f[R],
\f[V]big-sur\f[R] and \f[V]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[V]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[V]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[V]Name:\f[R] for the disk
.RS 2
.IP \[bu] 2
If you are installing macOS Mojave or later (Catalina, Big Sur, and
Monterey), choose any of the APFS options as the filesystem.
MacOS Extended may not work.
.RE
.IP \[bu] 2
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[V]guest_os=\[dq]macos\[dq]\f[R] instructs Quickemu to optimise for
macOS.
.IP \[bu] 2
\f[V]macos_release=\[dq]catalina\[dq]\f[R] instructs Quickemu to
optimise for a particular macOS release.
.RS 2
.IP \[bu] 2
For example VirtIO Network and Memory Ballooning are available in Big
Sur and newer, but not previous releases.
.IP \[bu] 2
And VirtIO Block Media (disks) are supported/stable in Catalina and
newer.
.RE
.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[V]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[V]usb-tablet\f[R] (http://philjordan.eu/osx-virt/) is used for
the mouse.
.IP \[bu] 2
VirtIO Network (\f[V]virtio-net\f[R]) is supported and enabled on macOS
Big Sur and newer but previous releases use \f[V]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
\f[B]Full Duplex audio requires VoodooHDA
OC (https://github.com/chris1111/VoodooHDA-OC) or pass-through a USB
audio-device to the macOS guest VM\f[R].
.IP \[bu] 2
NOTE!
Gatekeeper (https://disable-gatekeeper.github.io/) and System Integrity
Protection
(SIP) (https://developer.apple.com/documentation/security/disabling_and_enabling_system_integrity_protection)
need to be disabled to install VoodooHDA OC
.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 macOS App Store
.PP
If you see \f[I]\[lq]Your device or computer could not be
verified\[rq]\f[R] when you try to login to the App Store, make sure
that your wired ethernet device is \f[V]en0\f[R].
Use \f[V]ifconfig\f[R] in a terminal to verify this.
.PP
If the wired ethernet device is not \f[V]en0\f[R], then then go to
\f[I]System Preferences\f[R] -> \f[I]Network\f[R], delete all the
network devices and apply the changes.
Next, open a terminal and run the following:
.IP
.nf
\f[C]
sudo rm /Library/Preferences/SystemConfiguration/NetworkInterfaces.plist
\f[R]
.fi
.PP
Now reboot, and the App Store should work.
.SS Windows 8.1, 10 & 11 Guests
.PP
\f[V]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.
.IP \[bu] 2
A local adminstrator user account is automatically created, with these
credentials:
.RS 2
.IP \[bu] 2
Username: \f[V]Quickemu\f[R]
.IP \[bu] 2
Password: \f[V]quickemu\f[R]
.RE
.SS Regional versions
.PP
By default \f[V]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]
secureboot=\[dq]on\[dq]
\f[R]
.fi
.IP \[bu] 2
\f[V]guest_os=\[dq]windows\[dq]\f[R] instructs \f[V]quickemu\f[R] to
optimise for Windows.
.IP \[bu] 2
\f[V]fixed_iso=\f[R] specifies the ISO image that provides VirtIO
drivers.
.IP \[bu] 2
\f[V]tpm=\[dq]on\[dq]\f[R] instructs \f[V]quickemu\f[R] to create a
software emulated TPM device using \f[V]swtpm\f[R].
.SH 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.