quickemu/docs/quickget.1

.\" 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]freedos\f[R] (FreeDOS)
.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.