diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..71ea07e --- /dev/null +++ b/docs/Makefile @@ -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 diff --git a/docs/pandoc-man.mk b/docs/pandoc-man.mk new file mode 100644 index 0000000..90d6ecb --- /dev/null +++ b/docs/pandoc-man.mk @@ -0,0 +1,8 @@ +PANDOC ?= pandoc + +MANSECTION ?= 1 + +MANPAGE.md = $(PANDOC) --standalone $(PANDOCFLAGS) --to man + +%.$(MANSECTION): %.$(MANSECTION).md + $(MANPAGE.md) $< -o $@ \ No newline at end of file diff --git a/docs/quickemu.1 b/docs/quickemu.1 new file mode 100644 index 0000000..a150d44 --- /dev/null +++ b/docs/quickemu.1 @@ -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 \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 \f[R] +Apply/restore a snapshot. +.TP +\f[B]\[en]snapshot create \f[R] +Create a snapshot. +.TP +\f[B]\[en]snapshot delete \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 : Use specified screen to determine the window size. + --shortcut : Create a desktop shortcut + --snapshot apply : Apply/restore a snapshot. + --snapshot create : Create a snapshot. + --snapshot delete : 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 + +.IP \[bu] 2 + +.RE +.IP \[bu] 2 +macOS +.RS 2 +.IP \[bu] 2 + +.IP \[bu] 2 + +.IP \[bu] 2 + +.IP \[bu] 2 + +.IP \[bu] 2 + +.IP \[bu] 2 + +.IP \[bu] 2 + +.IP \[bu] 2 + +.IP \[bu] 2 + +.IP \[bu] 2 +OpenCore Configurator (https://mackie100projects.altervista.org) +.RE +.IP \[bu] 2 +Windows +.RS 2 +.IP \[bu] 2 + +.IP \[bu] 2 + +.IP \[bu] 2 + +.IP \[bu] 2 + +.IP \[bu] 2 + +.IP \[bu] 2 + +.RE +.IP \[bu] 2 +TPM +.RS 2 +.IP \[bu] 2 + +.IP \[bu] 2 + +.RE +.IP \[bu] 2 +9p & virtiofs +.RS 2 +.IP \[bu] 2 + +.IP \[bu] 2 + +.IP \[bu] 2 + +.IP \[bu] 2 + +.IP \[bu] 2 + +.RE +.SH AUTHORS +.PP +Written by Martin Wimpress. +.SH BUGS +.PP +Submit bug reports online at: + +.SH SEE ALSO +.PP +Full sources at: +.PP +quickemu_conf(1), quickget(1), quickgui(1) +.SH AUTHORS +Martin Wimpress. diff --git a/docs/quickemu.1.md b/docs/quickemu.1.md new file mode 100644 index 0000000..73531c2 --- /dev/null +++ b/docs/quickemu.1.md @@ -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 \** +: Use specified screen to determine the window size. + +**--shortcut** +: Create a desktop shortcut + +**--snapshot apply \** +: Apply/restore a snapshot. + +**--snapshot create \** +: Create a snapshot. + +**--snapshot delete \** +: 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 : Use specified screen to determine the window size. + --shortcut : Create a desktop shortcut + --snapshot apply : Apply/restore a snapshot. + --snapshot create : Create a snapshot. + --snapshot delete : 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/) + - + - +- macOS + - + - + - + - + - + - + - + - + - + - [OpenCore + Configurator](https://mackie100projects.altervista.org) +- Windows + - + - + - + - + - + - +- TPM + - + - +- 9p & virtiofs + - + - + - + - + - + +AUTHORS +======= + +Written by Martin Wimpress. + +BUGS +==== + +Submit bug reports online at: + + +SEE ALSO +======== + +Full sources at: + +quickemu\_conf(1), quickget(1), quickgui(1) diff --git a/docs/quickemu_conf.1 b/docs/quickemu_conf.1 new file mode 100644 index 0000000..5f3472f --- /dev/null +++ b/docs/quickemu_conf.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 .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 .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: + +.SH SEE ALSO +.PP +Full sources at: +.PP +quickget(1), quickemu(1), quickgui(1) +.SH AUTHORS +Martin Wimpress. diff --git a/docs/quickemu_conf.1.md b/docs/quickemu_conf.1.md new file mode 100644 index 0000000..a978739 --- /dev/null +++ b/docs/quickemu_conf.1.md @@ -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 \.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 \.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: + + +SEE ALSO +======== + +Full sources at: + +quickget(1), quickemu(1), quickgui(1) diff --git a/docs/quickget.1 b/docs/quickget.1 new file mode 100644 index 0000000..bd7506a --- /dev/null +++ b/docs/quickget.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: + +.SH SEE ALSO +.PP +Full sources at: +.PP +quickemu(1), quickemu_conf(1), quickgui(1) +.SH AUTHORS +Martin Wimpress. diff --git a/docs/quickget.1.md b/docs/quickget.1.md new file mode 100644 index 0000000..7eaa822 --- /dev/null +++ b/docs/quickget.1.md @@ -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: + + +SEE ALSO +======== + +Full sources at: + +quickemu(1), quickemu\_conf(1), quickgui(1)