From d0c2bb228a79356cd39ccf326a933c90aee9d420 Mon Sep 17 00:00:00 2001 From: Phil Clifford Date: Sat, 30 Jul 2022 07:56:23 +0100 Subject: [PATCH] New release docs with cogged README (#508) --- README.md | 274 ++++++++++++++++++++---------------- build-docs | 2 +- docs/quickemu.1 | 302 +++++++++++++++++++++++++--------------- docs/quickemu.1.md | 201 ++++++++++++++------------ docs/quickemu_conf.1 | 87 ++++++++---- docs/quickemu_conf.1.md | 97 ++++++------- docs/quickget.1 | 189 ++++++++++++++----------- docs/quickget.1.md | 70 +++++----- 8 files changed, 700 insertions(+), 522 deletions(-) diff --git a/README.md b/README.md index a015a2b..dc9b9d2 100644 --- a/README.md +++ b/README.md @@ -8,17 +8,16 @@
Quickemu Screenshot

Made with 💝 for

-Introduction ------------- +## 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 +``` bash +quickget ubuntu-mate 22.04 +quickemu --vm ubuntu-mate-22.04-.conf ``` The original objective of the project was to enable quick testing of @@ -28,8 +27,7 @@ and no elevated permissions are required to run the virtual machines. **Quickemu now also includes comprehensive support for macOS and Windows**. -Features --------- +## Features - **macOS** Monterey, Big Sur, Catalina, Mojave & High Sierra - **Windows** 8.1, 10 and 11 including TPM 2.0 @@ -67,8 +65,7 @@ Quickemu. [![Replace VirtualBox with Bash & QEMU](https://img.youtube.com/vi/AOTYWEgw0hI/0.jpg)](https://www.youtube.com/watch?v=AOTYWEgw0hI) -Requirements ------------- +## Requirements - [QEMU](https://www.qemu.org/) (*6.0.0 or newer*) **with GTK, SDL, SPICE & VirtFS support** @@ -93,11 +90,37 @@ Requirements - [zsync](http://zsync.moria.org.uk/) - [unzip](http://www.info-zip.org/UnZip.html) -Usage -===== +### Installing Requirements + +For Ubuntu, Arch and nixos systems the +[ppa](https://launchpad.net/~flexiondotorg/+archive/ubuntu/quickemu), +[AUR](https://aur.archlinux.org/packages/quickemu) or +[nix](https://github.com/NixOS/nixpkgs/tree/master/pkgs/development/quickemu) +packaging will take care of the dependencies. For other host +distributions or operating systems it will be necessary to install the +above requirements or their equivalents. + +These examples may save a little typing + +Debian: + + sudo apt install qemu bash coreutils ovmf grep jq lsb procps python3 genisoimage usbutils util-linux sed spice-client-gtk swtpm wget xdg-user-dirs zsync unzip + +Fedora: + + sudo dnf install qemu bash coreutils edk2-tools grep jq lsb procps python3 genisoimage usbutils util-linux sed spice-gtk-tools swtpm wget xdg-user-dirs xrandr unzip + +MacOS: + +This is a work in progress (see [issue +248](https://github.com/quickemu-project/quickemu/issues/248) for other +steps and changes that may enable running on MacOS) + + brew install qemu bash coreutils grep jq python@3.10 cdrtools gnu-sed spice-gtk wget zsync -Graphical User Interfaces -------------------------- +# Usage + +## Graphical User Interfaces While `quickemu` and `quickget` are designed for the terminal, a graphical user interface is also available: @@ -112,33 +135,30 @@ Many thanks to [Luke Wesley-Holley](https://github.com/Lukewh) and ### Quickgui for Ubuntu -``` {.bash} +``` bash sudo add-apt-repository ppa:yannick-mauray/quickgui sudo apt update sudo apt install quickgui ``` -Install Quickemu -================ +# Install Quickemu -Ubuntu ------- +## Ubuntu Quickemu is available from a PPA for Ubuntu users. The Quickemu PPA also includes a back port of QEMU 6.0.0 for 20.04 (Focal) and 21.04 (Hirsute). To install Quickemu and all the dependencies run the following in a terminal: -``` {.bash} +``` bash sudo apt-add-repository ppa:flexiondotorg/quickemu sudo apt update sudo apt install quickemu ``` -Other Linux ------------ +## Other Linux -``` {.bash} +``` bash git clone --depth=1 https://github.com/wimpysworld/quickemu cd quickemu ``` @@ -160,15 +180,14 @@ status](https://repology.org/badge/vertical-allrepos/quickemu.svg)](https://repo [![Packaging status](https://repology.org/badge/vertical-allrepos/quickgui.svg)](https://repology.org/project/quickgui/versions) -Ubuntu Guest ------------- +## 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 +``` bash +quickget ubuntu 22.04 +quickemu --vm ubuntu-22.04.conf ``` - Complete the installation as normal. @@ -185,7 +204,7 @@ quickemu --vm ubuntu-20.04.conf `quickget` can also download/refresh devel images via `zsync` for Ubuntu developers and testers. -``` {.bash} +``` bash quickget ubuntu devel quickemu --vm ubuntu-devel.conf ``` @@ -208,8 +227,7 @@ with your preferred flavour. - `ubuntu` (Ubuntu) - `xubuntu` (Xubuntu) -Other Operating Systems ------------------------ +## Other Operating Systems `quickget` also supports: @@ -218,11 +236,15 @@ Other Operating Systems - `android` (Android x86) - `archlinux` (Arch Linux) - `arcolinux` (Arco Linux) +- `batocera` (Batocera) - `cachyos` (CachyOS) +- `centos-stream` (CentOS Stream) - `debian` (Debian) +- `deepin` (Deepin) - `devuan` (Devuan) - `dragonflybsd` (DragonFlyBSD) - `elementary` (elementary OS) +- `endeavouros` (EndeavourOS) - `fedora` (Fedora) - `freebsd` (FreeBSD) - `freedos` (FreeDOS) @@ -234,6 +256,7 @@ Other Operating Systems - `kdeneon` (KDE Neon) - `kolibrios` (KolibriOS) - `linuxmint` (Linux Mint) +- `lmde` (Linux Mint Debian Edition) - `manjaro` (Manjaro) - `mxlinux` (MX Linux) - `netboot` (netboot.xyz) @@ -257,7 +280,7 @@ configuration. - Download a .iso image of a Linux distribution - Create a VM configuration file; for example `debian-bullseye.conf` -``` {.bash} +``` bash guest_os="linux" disk_img="debian-bullseye/disk.qcow2" iso="debian-bullseye/firmware-11.0.0-amd64-DVD-1.iso" @@ -265,7 +288,7 @@ iso="debian-bullseye/firmware-11.0.0-amd64-DVD-1.iso" - Use `quickemu` to start the virtual machine: -``` {.bash} +``` bash quickemu --vm debian-bullseye.conf ``` @@ -276,13 +299,12 @@ quickemu --vm debian-bullseye.conf - Install the SPICE WebDAV agent (`spice-webdavd`) to enable file sharing. -macOS Guest ------------ +## macOS Guest `quickget` automatically downloads a macOS recovery image and creates a virtual machine configuration. -``` {.bash} +``` bash quickget macos catalina quickemu --vm macos-catalina.conf ``` @@ -312,7 +334,7 @@ supported. The default macOS configuration looks like this: -``` {.bash} +``` bash guest_os="macos" img="macos-catalina/RecoveryImage.img" disk_img="macos-catalina/disk.qcow2" @@ -363,8 +385,7 @@ There are some considerations when running macOS via Quickemu. 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 ---------------------------- +## 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 @@ -374,7 +395,7 @@ with the [VirtIO drivers for Windows](https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/) and creates a virtual machine configuration. -``` {.bash} +``` bash quickget windows 11 quickemu --vm windows-11.conf ``` @@ -388,13 +409,13 @@ By default `quickget` will download the *"English International"* release, but you can optionally specify one of the supported languages: For example: -``` {.bash} +``` bash quickget windows 11 "Chinese (Traditional)" ``` The default Windows 11 configuration looks like this: -``` {.bash} +``` bash guest_os="windows" disk_img="windows-11/disk.qcow2" iso="windows-11/Win11_EnglishInternational_x64.iso" @@ -408,8 +429,7 @@ secureboot="on" - `tpm="on"` instructs `quickemu` to create a software emulated TPM device using `swtpm`. -SPICE -===== +# SPICE The following features are available while using the SPICE protocol: @@ -421,51 +441,49 @@ To use SPICE add `--display spice` to the Quickemu invocation, this requires that the `spicy` client is installed, available from the `spice-client-gtk` package in Debian/Ubuntu. -``` {.bash} -quickemu --vm ubuntu-20.04.conf --display spice +``` bash +quickemu --vm ubuntu-22.04.conf --display spice ``` -To enable copy/paste with a Windows guest, install [SPICE Windows guest tools](https://www.spice-space.org/download.html) in the guest VM. +To enable copy/paste with a Windows guest, install [SPICE Windows guest +tools](https://www.spice-space.org/download.html) in the guest VM. -Headless --------- +## Headless To start a VM with SPICE enabled, but no display attached use `--display none`. This requires that the `spicy` client is installed, available from the `spice-client-gtk` package in Debian/Ubuntu to connect to the running VM -``` {.bash} -quickemu --vm ubuntu-20.04.conf --display none +``` bash +quickemu --vm ubuntu-22.04.conf --display none ``` You can also use the `.ports` file in the VM directory to lookup what SSH and SPICE ports the VM is connected to. -``` {.bash} -cat ubuntu-20.04/ubuntu-20.04.ports +``` bash +cat ubuntu-22.04/ubuntu-22.04.ports ``` If, for example, the SSH port is set to 22220, and assuming your VM has a started SSH service (details vary by OS), you can typically SSH into it from the host as follows: -``` {.bash} +``` bash ssh -p 22220 your_vm_user@localhost ``` -Accessibility -============= +# Accessibility Qemu provides support for using BrlAPI to display braille output on a real or fake device. -``` {.bash} -quickemu --vm ubuntu-21.10.conf --braille --display sdl +``` bash +quickemu --vm ubuntu-22.04.conf --braille --display sdl ``` -BIOS and EFI -============ +# 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 @@ -473,8 +491,7 @@ configuration to enable legacy BIOS. - `boot="legacy"` - Enable Legacy BIOS boot -Tuning CPU cores, RAM & disks -============================= +# 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 @@ -489,8 +506,7 @@ Add additional lines to your virtual machine configuration: - `disk_size="16G"` - Specify the size of the virtual disk allocated to the VM -Disk preallocation ------------------- +## Disk preallocation Preallocation mode (allowed values: `off` (default), `metadata`, `falloc`, `full`). An image with preallocated metadata is initially @@ -502,16 +518,14 @@ configuration. - `preallocation="metadata"` -CD-ROM disks ------------- +## 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 ------------- +## 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 @@ -519,14 +533,12 @@ to the VM configuration: - `floppy="/path/to/floppy.img"` -File Sharing -============ +# File Sharing All File Sharing options will only expose `~/Public` (or localised variations) for the current user to the guest VMs. -Samba 🐧 🍏 🪟 ------------ +## 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 @@ -534,22 +546,28 @@ the guest. You can install the minimal Samba components on Ubuntu using: -``` {.bash} +``` bash sudo apt install --no-install-recommends samba ``` -SPICE WebDAV 🐧 🪟 ----------------- +If everything is set up correctly, the `smbd` address will be printed +when the virtual machine is started. For example: + + - smbd: On guest: smb://10.0.2.4/qemu + +If using a Windows guest, right-click on "This PC", click "Add a network +location", and paste this address, removing `smb:` and replacing forward +slashes with backslashes (in this example `\\10.0.2.4\qemu`). + +## SPICE WebDAV 🐧 🪟 - TBD -VirtIO-9P 🐧 🍏 -------------- +## VirtIO-9P 🐧 🍏 - TBD -Network port forwarding -======================= +# Network port forwarding Add an additional line to your virtual machine configuration. For example: @@ -561,30 +579,26 @@ 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 -================== +# Bridged networking Connect your virtual machine to a preconfigured network bridge. Add an additional line to your virtual machine configuration - `bridge="br0"` -USB redirection -=============== +# USB redirection Quickemu supports USB redirection via SPICE pass-through and host pass-through. -SPICE redirection (recommended) -------------------------------- +## 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** ------------------------------------- +## 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 @@ -597,9 +611,9 @@ example: In the example above: -- The USB device with vendor\_id 046d and product\_id 082d will be +- 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 +- 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 @@ -611,55 +625,80 @@ like this: sudo chown -v root:user /dev/bus/usb/001/005 ERROR! USB permission changes are required 👆 -TPM -=== +# 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. -All the options -=============== +# 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 + --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. + --viewer : Choose an alternative viewer. @Options: 'spicy' (default), 'remote-viewer', 'none' + --ssh-port : Set ssh-port manually + --spice-port : Set spice-port manually + --public-dir : expose share directory. @Options: '' (default: xdg-user-dir PUBLICSHARE), '', 'none' + --monitor : Set monitor connection type. @Options: 'socket' (default), 'telnet', 'none' + --monitor-telnet-host : Set telnet host for monitor. (default: 'localhost') + --monitor-telnet-port : Set telnet port for monitor. (default: '4440') + --monitor-cmd : Send command to monitor if available. (Example: system_powerdown) + --serial : Set serial connection type. @Options: 'socket' (default), 'telnet', 'none' + --serial-telnet-host : Set telnet host for serial. (default: 'localhost') + --serial-telnet-port : Set telnet port for serial. (default: '6660') + --keyboard : Set keyboard. @Options: 'usb' (default), 'ps2', 'virtio' + --keyboard_layout : Set keyboard layout. + --mouse : Set mouse. @Options: 'tablet' (default), 'ps2', 'usb', 'virtio' + --usb-controller : Set usb-controller. @Options: 'ehci' (default), 'xhci', 'none' + --extra_args : Pass additional arguments to qemu + --version : Print version + ``` -Desktop shortcuts ------------------ + + +## 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 +``` bash +quickemu --vm ubuntu-22.04-desktop.conf --shortcut ``` -Screen and window size (Linux guests only) ------------------------------------------- +## Screen and window size (Linux guests only) `qemu` will always default to the primary monitor to display the VM's window. @@ -680,13 +719,13 @@ must match the resolution of the screen. To know which screen to use, type: -``` {.bash} +``` bash xrandr --listmonitors | grep -v Monitors ``` The command will output something like this: -``` {.bash} +``` bash 0: +*HDMI-0 2560/597x1440/336+1920+0 HDMI-0 1: +DVI-D-0 1920/527x1080/296+0+0 DVI-D-0 ``` @@ -695,7 +734,7 @@ The first number is what needs to be passed to the `--screen` option. For example: -``` {.bash} +``` bash quickemu --vm vm.conf --screen 0 ``` @@ -704,8 +743,7 @@ 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 -========== +# References Useful reference that assisted the development of Quickemu. diff --git a/build-docs b/build-docs index 3ede604..51ee39c 160000 --- a/build-docs +++ b/build-docs @@ -1 +1 @@ -Subproject commit 3ede604a11b7a666f91bb19705d32d73fb0bd4d7 +Subproject commit 51ee39c41c13fb1cc78e86ec24b100f35c337d70 diff --git a/docs/quickemu.1 b/docs/quickemu.1 index 75ec017..77de3ae 100644 --- a/docs/quickemu.1 +++ b/docs/quickemu.1 @@ -1,6 +1,20 @@ -.\" Automatically generated by Pandoc 2.9.2.1 +.\" Automatically generated by Pandoc 2.18 .\" -.TH "QUICKEMU" "1" "February 20, 2022" "quickemu" "Quickemu User Manual" +.\" 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 "QUICKEMU" "1" "July 30, 2022" "quickemu" "Quickemu User Manual" .hy .SH NAME .PP @@ -61,8 +75,8 @@ Do not commit any changes to disk/snapshot. 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] +\f[B]quickemu \[en]vm ubuntu-mate-22.04-.conf\f[R] +Launches the VM specified in the file \f[I]ubuntu-mate-22.04-.conf\f[R] .SS Introduction .PP Quickly create and run highly optimised desktop virtual machines for @@ -73,8 +87,8 @@ For example: .IP .nf \f[C] -quickget ubuntu-mate 21.10 -quickemu --vm ubuntu-mate-21.10-.conf +quickget ubuntu-mate 22.04 +quickemu --vm ubuntu-mate-22.04-.conf \f[R] .fi .PP @@ -105,7 +119,7 @@ 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]) +\f[VI]smbd\f[I] is installed on the host\f[R]) .IP \[bu] 2 VirGL acceleration .IP \[bu] 2 @@ -181,10 +195,49 @@ xrandr (https://gitlab.freedesktop.org/xorg/app/xrandr) zsync (http://zsync.moria.org.uk/) .IP \[bu] 2 unzip (http://www.info-zip.org/UnZip.html) +.SS Installing Requirements +.PP +For Ubuntu, Arch and nixos systems the +ppa (https://launchpad.net/~flexiondotorg/+archive/ubuntu/quickemu), +AUR (https://aur.archlinux.org/packages/quickemu) or +nix (https://github.com/NixOS/nixpkgs/tree/master/pkgs/development/quickemu) +packaging will take care of the dependencies. +For other host distributions or operating systems it will be necessary +to install the above requirements or their equivalents. +.PP +These examples may save a little typing +.PP +Debian: +.IP +.nf +\f[C] +sudo apt install qemu bash coreutils ovmf grep jq lsb procps python3 genisoimage usbutils util-linux sed spice-client-gtk swtpm wget xdg-user-dirs zsync unzip +\f[R] +.fi +.PP +Fedora: +.IP +.nf +\f[C] +sudo dnf install qemu bash coreutils edk2-tools grep jq lsb procps python3 genisoimage usbutils util-linux sed spice-gtk-tools swtpm wget xdg-user-dirs xrandr unzip +\f[R] +.fi +.PP +MacOS: +.PP +This is a work in progress (see issue +248 (https://github.com/quickemu-project/quickemu/issues/248) for other +steps and changes that may enable running on MacOS) +.IP +.nf +\f[C] +brew install qemu bash coreutils grep jq python\[at]3.10 cdrtools gnu-sed spice-gtk wget zsync +\f[R] +.fi .SH Usage .SS Graphical User Interfaces .PP -While \f[C]quickemu\f[R] and \f[C]quickget\f[R] are designed for the +While \f[V]quickemu\f[R] and \f[V]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 @@ -206,13 +259,13 @@ sudo apt install quickgui .fi .SS Ubuntu Guest .PP -\f[C]quickget\f[R] will automatically download an Ubuntu release and +\f[V]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 +quickget ubuntu 22.04 +quickemu --vm ubuntu-22.04.conf \f[R] .fi .IP \[bu] 2 @@ -221,24 +274,24 @@ Complete the installation as normal. Post-install: .RS 2 .IP \[bu] 2 -Install the SPICE agent (\f[C]spice-vdagent\f[R]) to enable copy/paste +Install the SPICE agent (\f[V]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] +\f[V]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 +Install the SPICE WebDAV agent (\f[V]spice-webdavd\f[R]) to enable file sharing. .RS 2 .IP \[bu] 2 -\f[C]sudo apt install spice-webdavd\f[R] +\f[V]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. +\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] @@ -247,106 +300,116 @@ quickemu --vm ubuntu-devel.conf \f[R] .fi .PP -You can run \f[C]quickget ubuntu devel\f[R] to refresh your daily +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[C]ubuntu\f[R] with your preferred flavour. +\f[V]ubuntu\f[R] with your preferred flavour. .IP \[bu] 2 -\f[C]kubuntu\f[R] (Kubuntu) +\f[V]kubuntu\f[R] (Kubuntu) .IP \[bu] 2 -\f[C]lubuntu\f[R] (Lubuntu) +\f[V]lubuntu\f[R] (Lubuntu) .IP \[bu] 2 -\f[C]ubuntu-budgie\f[R] (Ubuntu Budgie) +\f[V]ubuntu-budgie\f[R] (Ubuntu Budgie) .IP \[bu] 2 -\f[C]ubuntukylin\f[R] (Ubuntu Kylin) +\f[V]ubuntukylin\f[R] (Ubuntu Kylin) .IP \[bu] 2 -\f[C]ubuntu-mate\f[R] (Ubuntu MATE) +\f[V]ubuntu-mate\f[R] (Ubuntu MATE) .IP \[bu] 2 -\f[C]ubuntustudio\f[R] (Ubuntu Studio) +\f[V]ubuntustudio\f[R] (Ubuntu Studio) .IP \[bu] 2 -\f[C]ubuntu\f[R] (Ubuntu) +\f[V]ubuntu\f[R] (Ubuntu) .IP \[bu] 2 -\f[C]xubuntu\f[R] (Xubuntu) +\f[V]xubuntu\f[R] (Xubuntu) .SS Other Operating Systems .PP -\f[C]quickget\f[R] also supports: +\f[V]quickget\f[R] also supports: .IP \[bu] 2 -\f[C]alma\f[R] (Alma Linux) +\f[V]alma\f[R] (Alma Linux) .IP \[bu] 2 -\f[C]alpine\f[R] (Alpine Linux) +\f[V]alpine\f[R] (Alpine Linux) .IP \[bu] 2 -\f[C]android\f[R] (Android x86) +\f[V]android\f[R] (Android x86) .IP \[bu] 2 -\f[C]archlinux\f[R] (Arch Linux) +\f[V]archlinux\f[R] (Arch Linux) .IP \[bu] 2 -\f[C]arcolinux\f[R] (Arco Linux) +\f[V]arcolinux\f[R] (Arco Linux) .IP \[bu] 2 -\f[C]cachyos\f[R] (CachyOS) +\f[V]batocera\f[R] (Batocera) .IP \[bu] 2 -\f[C]debian\f[R] (Debian) +\f[V]cachyos\f[R] (CachyOS) .IP \[bu] 2 -\f[C]devuan\f[R] (Devuan) +\f[V]centos-stream\f[R] (CentOS Stream) .IP \[bu] 2 -\f[C]dragonflybsd\f[R] (DragonFlyBSD) +\f[V]debian\f[R] (Debian) .IP \[bu] 2 -\f[C]elementary\f[R] (elementary OS) +\f[V]deepin\f[R] (Deepin) .IP \[bu] 2 -\f[C]fedora\f[R] (Fedora) +\f[V]devuan\f[R] (Devuan) .IP \[bu] 2 -\f[C]freebsd\f[R] (FreeBSD) +\f[V]dragonflybsd\f[R] (DragonFlyBSD) .IP \[bu] 2 -\f[C]freedos\f[R] (FreeDOS) +\f[V]elementary\f[R] (elementary OS) .IP \[bu] 2 -\f[C]garuda\f[R] (Garuda Linux) +\f[V]endeavouros\f[R] (EndeavourOS) .IP \[bu] 2 -\f[C]gentoo\f[R] (Gentoo) +\f[V]fedora\f[R] (Fedora) .IP \[bu] 2 -\f[C]ghostbsd\f[R] (GhostBSD) +\f[V]freebsd\f[R] (FreeBSD) .IP \[bu] 2 -\f[C]haiku\f[R] (Haiku) +\f[V]freedos\f[R] (FreeDOS) .IP \[bu] 2 -\f[C]kali\f[R] (Kali) +\f[V]garuda\f[R] (Garuda Linux) .IP \[bu] 2 -\f[C]kdeneon\f[R] (KDE Neon) +\f[V]gentoo\f[R] (Gentoo) .IP \[bu] 2 -\f[C]kolibrios\f[R] (KolibriOS) +\f[V]ghostbsd\f[R] (GhostBSD) .IP \[bu] 2 -\f[C]linuxmint\f[R] (Linux Mint) +\f[V]haiku\f[R] (Haiku) .IP \[bu] 2 -\f[C]manjaro\f[R] (Manjaro) +\f[V]kali\f[R] (Kali) .IP \[bu] 2 -\f[C]mxlinux\f[R] (MX Linux) +\f[V]kdeneon\f[R] (KDE Neon) .IP \[bu] 2 -\f[C]netboot\f[R] (netboot.xyz) +\f[V]kolibrios\f[R] (KolibriOS) .IP \[bu] 2 -\f[C]netbsd\f[R] (NetBSD) +\f[V]linuxmint\f[R] (Linux Mint) .IP \[bu] 2 -\f[C]nixos\f[R] (NixOS) +\f[V]lmde\f[R] (Linux Mint Debian Edition) .IP \[bu] 2 -\f[C]openbsd\f[R] (OpenBSD) +\f[V]manjaro\f[R] (Manjaro) .IP \[bu] 2 -\f[C]opensuse\f[R] (openSUSE) +\f[V]mxlinux\f[R] (MX Linux) .IP \[bu] 2 -\f[C]oraclelinux\f[R] (Oracle Linux) +\f[V]netboot\f[R] (netboot.xyz) .IP \[bu] 2 -\f[C]popos\f[R] (Pop!_OS) +\f[V]netbsd\f[R] (NetBSD) .IP \[bu] 2 -\f[C]regolith\f[R] (Regolith Linux) +\f[V]nixos\f[R] (NixOS) .IP \[bu] 2 -\f[C]rockylinux\f[R] (Rocky Linux) +\f[V]openbsd\f[R] (OpenBSD) .IP \[bu] 2 -\f[C]slackware\f[R] (Slackware) +\f[V]opensuse\f[R] (openSUSE) .IP \[bu] 2 -\f[C]solus\f[R] (Solus) +\f[V]oraclelinux\f[R] (Oracle Linux) .IP \[bu] 2 -\f[C]tails\f[R] (Tails) +\f[V]popos\f[R] (Pop!_OS) .IP \[bu] 2 -\f[C]void\f[R] (Void Linux) +\f[V]regolith\f[R] (Regolith Linux) .IP \[bu] 2 -\f[C]zorin\f[R] (Zorin OS) +\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. @@ -354,7 +417,7 @@ configuration. 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] +\f[V]debian-bullseye.conf\f[R] .IP .nf \f[C] @@ -364,7 +427,7 @@ 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: +Use \f[V]quickemu\f[R] to start the virtual machine: .IP .nf \f[C] @@ -377,15 +440,15 @@ Complete the installation as normal. Post-install: .RS 2 .IP \[bu] 2 -Install the SPICE agent (\f[C]spice-vdagent\f[R]) to enable copy/paste +Install the SPICE agent (\f[V]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 +Install the SPICE WebDAV agent (\f[V]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 +\f[V]quickget\f[R] automatically downloads a macOS recovery image and creates a virtual machine configuration. .IP .nf @@ -395,8 +458,8 @@ 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. +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 @@ -409,19 +472,19 @@ Click \f[B]Disk Utility\f[R] and \f[B]Continue\f[R] 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 +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[C]QEMU HARDDISK Media\f[R] (\[ti]103.08GB) from the list and +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[C]Name:\f[R] for the disk and click \f[B]Erase\f[R]. +Enter a \f[V]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 @@ -455,10 +518,10 @@ 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 +\f[V]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 +\f[V]macos_release=\[dq]catalina\[dq]\f[R] instructs Quickemu to optimise for a particular macOS release. .RS 2 .IP \[bu] 2 @@ -486,7 +549,7 @@ Big Sur Monterey .RE .IP \[bu] 2 -\f[C]quickemu\f[R] will automatically download the required +\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 @@ -499,11 +562,11 @@ 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 +VirtIO \f[V]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]. +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. @@ -532,7 +595,7 @@ webdavd (https://gitlab.gnome.org/GNOME/phodav/-/merge_requests/24). 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 +\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 @@ -551,7 +614,7 @@ Complete the installation as you normally would. 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 +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 @@ -570,74 +633,89 @@ 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[C]guest_os=\[dq]windows\[dq]\f[R] instructs \f[C]quickemu\f[R] to +\f[V]guest_os=\[dq]windows\[dq]\f[R] instructs \f[V]quickemu\f[R] to optimise for Windows. .IP \[bu] 2 -\f[C]fixed_iso=\f[R] specifies the ISO image that provides VirtIO +\f[V]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]. +\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 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 - + --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. + --viewer : Choose an alternative viewer. \[at]Options: \[aq]spicy\[aq] (default), \[aq]remote-viewer\[aq], \[aq]none\[aq] + --ssh-port : Set ssh-port manually + --spice-port : Set spice-port manually + --public-dir : expose share directory. \[at]Options: \[aq]\[aq] (default: xdg-user-dir PUBLICSHARE), \[aq]\[aq], \[aq]none\[aq] + --monitor : Set monitor connection type. \[at]Options: \[aq]socket\[aq] (default), \[aq]telnet\[aq], \[aq]none\[aq] + --monitor-telnet-host : Set telnet host for monitor. (default: \[aq]localhost\[aq]) + --monitor-telnet-port : Set telnet port for monitor. (default: \[aq]4440\[aq]) + --monitor-cmd : Send command to monitor if available. (Example: system_powerdown) + --serial : Set serial connection type. \[at]Options: \[aq]socket\[aq] (default), \[aq]telnet\[aq], \[aq]none\[aq] + --serial-telnet-host : Set telnet host for serial. (default: \[aq]localhost\[aq]) + --serial-telnet-port : Set telnet port for serial. (default: \[aq]6660\[aq]) + --keyboard : Set keyboard. \[at]Options: \[aq]usb\[aq] (default), \[aq]ps2\[aq], \[aq]virtio\[aq] + --keyboard_layout : Set keyboard layout. + --mouse : Set mouse. \[at]Options: \[aq]tablet\[aq] (default), \[aq]ps2\[aq], \[aq]usb\[aq], \[aq]virtio\[aq] + --usb-controller : Set usb-controller. \[at]Options: \[aq]ehci\[aq] (default), \[aq]xhci\[aq], \[aq]none\[aq] + --extra_args : Pass additional arguments to qemu + --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]. +\f[V]\[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 +quickemu --vm ubuntu-22.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 +\f[V]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 +Without the \f[V]--screen\f[R] option, \f[V]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 +The \f[V]--screen\f[R] option forces \f[V]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 +The \f[V]--screen\f[R] option is also useful with the +\f[V]--fullscreen\f[R] option, again because \f[V]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. @@ -659,7 +737,7 @@ The command will output something like this: \f[R] .fi .PP -The first number is what needs to be passed to the \f[C]--screen\f[R] +The first number is what needs to be passed to the \f[V]--screen\f[R] option. .PP For example: @@ -672,7 +750,7 @@ quickemu --vm vm.conf --screen 0 .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 +Without the \f[V]--screen\f[R] option, Quickemu would have used the 1920x1080 monitor which results in a window size of 1664x936. .SH References .PP diff --git a/docs/quickemu.1.md b/docs/quickemu.1.md index c1d878d..66a98e7 100644 --- a/docs/quickemu.1.md +++ b/docs/quickemu.1.md @@ -1,30 +1,26 @@ --- author: Martin Wimpress -date: 'February 20, 2022' +date: July 30, 2022 footer: quickemu header: Quickemu User Manual section: 1 title: QUICKEMU --- -NAME -==== +# NAME quickemu - A quick VM builder and manager -SYNOPSIS -======== +# SYNOPSIS **quickemu** \[*OPTION*\]... -DESCRIPTION -=========== +# DESCRIPTION **quickemu** will create and run highly optimised desktop virtual machines for Linux, macOS and Windows -OPTIONS -======= +# OPTIONS **--vm** : vm configuration file @@ -70,23 +66,21 @@ You can also pass optional parameters **--version** : Print version -EXAMPLES -======== +# EXAMPLES -**quickemu --vm ubuntu-mate-21.10-.conf** -: Launches the VM specified in the file *ubuntu-mate-21.10-.conf* +**quickemu --vm ubuntu-mate-22.04-.conf** +: Launches the VM specified in the file *ubuntu-mate-22.04-.conf* -Introduction ------------- +## 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 +``` bash +quickget ubuntu-mate 22.04 +quickemu --vm ubuntu-mate-22.04-.conf ``` The original objective of the project was to enable quick testing of @@ -96,8 +90,7 @@ and no elevated permissions are required to run the virtual machines. **Quickemu now also includes comprehensive support for macOS and Windows**. -Features --------- +## Features - **macOS** Monterey, Big Sur, Catalina, Mojave & High Sierra - **Windows** 8.1, 10 and 11 including TPM 2.0 @@ -135,8 +128,7 @@ Quickemu. [![Replace VirtualBox with Bash & QEMU](https://img.youtube.com/vi/AOTYWEgw0hI/0.jpg)](https://www.youtube.com/watch?v=AOTYWEgw0hI) -Requirements ------------- +## Requirements - [QEMU](https://www.qemu.org/) (*6.0.0 or newer*) **with GTK, SDL, SPICE & VirtFS support** @@ -161,11 +153,37 @@ Requirements - [zsync](http://zsync.moria.org.uk/) - [unzip](http://www.info-zip.org/UnZip.html) -Usage -===== +### Installing Requirements -Graphical User Interfaces -------------------------- +For Ubuntu, Arch and nixos systems the +[ppa](https://launchpad.net/~flexiondotorg/+archive/ubuntu/quickemu), +[AUR](https://aur.archlinux.org/packages/quickemu) or +[nix](https://github.com/NixOS/nixpkgs/tree/master/pkgs/development/quickemu) +packaging will take care of the dependencies. For other host +distributions or operating systems it will be necessary to install the +above requirements or their equivalents. + +These examples may save a little typing + +Debian: + + sudo apt install qemu bash coreutils ovmf grep jq lsb procps python3 genisoimage usbutils util-linux sed spice-client-gtk swtpm wget xdg-user-dirs zsync unzip + +Fedora: + + sudo dnf install qemu bash coreutils edk2-tools grep jq lsb procps python3 genisoimage usbutils util-linux sed spice-gtk-tools swtpm wget xdg-user-dirs xrandr unzip + +MacOS: + +This is a work in progress (see [issue +248](https://github.com/quickemu-project/quickemu/issues/248) for other +steps and changes that may enable running on MacOS) + + brew install qemu bash coreutils grep jq python@3.10 cdrtools gnu-sed spice-gtk wget zsync + +# Usage + +## Graphical User Interfaces While `quickemu` and `quickget` are designed for the terminal, a graphical user interface is also available: @@ -180,21 +198,20 @@ Many thanks to [Luke Wesley-Holley](https://github.com/Lukewh) and ### Quickgui for Ubuntu -``` {.bash} +``` bash sudo add-apt-repository ppa:yannick-mauray/quickgui sudo apt update sudo apt install quickgui ``` -Ubuntu Guest ------------- +## 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 +``` bash +quickget ubuntu 22.04 +quickemu --vm ubuntu-22.04.conf ``` - Complete the installation as normal. @@ -211,7 +228,7 @@ quickemu --vm ubuntu-20.04.conf `quickget` can also download/refresh devel images via `zsync` for Ubuntu developers and testers. -``` {.bash} +``` bash quickget ubuntu devel quickemu --vm ubuntu-devel.conf ``` @@ -234,8 +251,7 @@ with your preferred flavour. - `ubuntu` (Ubuntu) - `xubuntu` (Xubuntu) -Other Operating Systems ------------------------ +## Other Operating Systems `quickget` also supports: @@ -244,11 +260,15 @@ Other Operating Systems - `android` (Android x86) - `archlinux` (Arch Linux) - `arcolinux` (Arco Linux) +- `batocera` (Batocera) - `cachyos` (CachyOS) +- `centos-stream` (CentOS Stream) - `debian` (Debian) +- `deepin` (Deepin) - `devuan` (Devuan) - `dragonflybsd` (DragonFlyBSD) - `elementary` (elementary OS) +- `endeavouros` (EndeavourOS) - `fedora` (Fedora) - `freebsd` (FreeBSD) - `freedos` (FreeDOS) @@ -260,6 +280,7 @@ Other Operating Systems - `kdeneon` (KDE Neon) - `kolibrios` (KolibriOS) - `linuxmint` (Linux Mint) +- `lmde` (Linux Mint Debian Edition) - `manjaro` (Manjaro) - `mxlinux` (MX Linux) - `netboot` (netboot.xyz) @@ -283,7 +304,7 @@ configuration. - Download a .iso image of a Linux distribution - Create a VM configuration file; for example `debian-bullseye.conf` -``` {.bash} +``` bash guest_os="linux" disk_img="debian-bullseye/disk.qcow2" iso="debian-bullseye/firmware-11.0.0-amd64-DVD-1.iso" @@ -291,7 +312,7 @@ iso="debian-bullseye/firmware-11.0.0-amd64-DVD-1.iso" - Use `quickemu` to start the virtual machine: -``` {.bash} +``` bash quickemu --vm debian-bullseye.conf ``` @@ -302,13 +323,12 @@ quickemu --vm debian-bullseye.conf - Install the SPICE WebDAV agent (`spice-webdavd`) to enable file sharing. -macOS Guest ------------ +## macOS Guest `quickget` automatically downloads a macOS recovery image and creates a virtual machine configuration. -``` {.bash} +``` bash quickget macos catalina quickemu --vm macos-catalina.conf ``` @@ -338,7 +358,7 @@ supported. The default macOS configuration looks like this: -``` {.bash} +``` bash guest_os="macos" img="macos-catalina/RecoveryImage.img" disk_img="macos-catalina/disk.qcow2" @@ -389,8 +409,7 @@ There are some considerations when running macOS via Quickemu. 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 ---------------------------- +## 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 @@ -400,7 +419,7 @@ with the [VirtIO drivers for Windows](https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/) and creates a virtual machine configuration. -``` {.bash} +``` bash quickget windows 11 quickemu --vm windows-11.conf ``` @@ -414,18 +433,19 @@ By default `quickget` will download the *"English International"* release, but you can optionally specify one of the supported languages: For example: -``` {.bash} +``` bash quickget windows 11 "Chinese (Traditional)" ``` The default Windows 11 configuration looks like this: -``` {.bash} +``` 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" +secureboot="on" ``` - `guest_os="windows"` instructs `quickemu` to optimise for Windows. @@ -433,47 +453,58 @@ tpm="on" - `tpm="on"` instructs `quickemu` to create a software emulated TPM device using `swtpm`. -All the options -=============== +# 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 ------------------ + 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. + --viewer : Choose an alternative viewer. @Options: 'spicy' (default), 'remote-viewer', 'none' + --ssh-port : Set ssh-port manually + --spice-port : Set spice-port manually + --public-dir : expose share directory. @Options: '' (default: xdg-user-dir PUBLICSHARE), '', 'none' + --monitor : Set monitor connection type. @Options: 'socket' (default), 'telnet', 'none' + --monitor-telnet-host : Set telnet host for monitor. (default: 'localhost') + --monitor-telnet-port : Set telnet port for monitor. (default: '4440') + --monitor-cmd : Send command to monitor if available. (Example: system_powerdown) + --serial : Set serial connection type. @Options: 'socket' (default), 'telnet', 'none' + --serial-telnet-host : Set telnet host for serial. (default: 'localhost') + --serial-telnet-port : Set telnet port for serial. (default: '6660') + --keyboard : Set keyboard. @Options: 'usb' (default), 'ps2', 'virtio' + --keyboard_layout : Set keyboard layout. + --mouse : Set mouse. @Options: 'tablet' (default), 'ps2', 'usb', 'virtio' + --usb-controller : Set usb-controller. @Options: 'ehci' (default), 'xhci', 'none' + --extra_args : Pass additional arguments to qemu + --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 +``` bash +quickemu --vm ubuntu-22.04-desktop.conf --shortcut ``` -Screen and window size (Linux guests only) ------------------------------------------- +## Screen and window size (Linux guests only) `qemu` will always default to the primary monitor to display the VM's window. @@ -494,13 +525,13 @@ must match the resolution of the screen. To know which screen to use, type: -``` {.bash} +``` bash xrandr --listmonitors | grep -v Monitors ``` The command will output something like this: -``` {.bash} +``` bash 0: +*HDMI-0 2560/597x1440/336+1920+0 HDMI-0 1: +DVI-D-0 1920/527x1080/296+0+0 DVI-D-0 ``` @@ -509,7 +540,7 @@ The first number is what needs to be passed to the `--screen` option. For example: -``` {.bash} +``` bash quickemu --vm vm.conf --screen 0 ``` @@ -518,8 +549,7 @@ 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 -========== +# References Useful reference that assisted the development of Quickemu. @@ -556,20 +586,17 @@ Useful reference that assisted the development of Quickemu. - - -AUTHORS -======= +# AUTHORS Written by Martin Wimpress. -BUGS -==== +# BUGS Submit bug reports online at: -SEE ALSO -======== +# SEE ALSO Full sources at: -quickemu\_conf(1), quickget(1), quickgui(1) +quickemu_conf(1), quickget(1), quickgui(1) diff --git a/docs/quickemu_conf.1 b/docs/quickemu_conf.1 index 5f3472f..5fa43b7 100644 --- a/docs/quickemu_conf.1 +++ b/docs/quickemu_conf.1 @@ -1,6 +1,20 @@ -.\" Automatically generated by Pandoc 2.9.2.1 +.\" Automatically generated by Pandoc 2.18 .\" -.TH "QUICKEMU_CONF" "1" "February 20, 2022" "quickemu_conf" "Quickemu Configuration Manual" +.\" 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 "QUICKEMU_CONF" "1" "July 30, 2022" "quickemu_conf" "Quickemu Configuration Manual" .hy .SH NAME .PP @@ -60,10 +74,10 @@ 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 +\f[V]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 +\f[V]macos_release=\[dq]catalina\[dq]\f[R] instructs Quickemu to optimise for a particular macOS release. .RS 2 .IP \[bu] 2 @@ -86,21 +100,21 @@ 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 +\f[V]guest_os=\[dq]windows\[dq]\f[R] instructs \f[V]quickemu\f[R] to optimise for Windows. .IP \[bu] 2 -\f[C]fixed_iso=\f[R] specifies the ISO image that provides VirtIO +\f[V]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]. +\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 BIOS and EFI .PP -Since Quickemu 2.1.0 \f[C]efi\f[R] is the default boot option. +Since Quickemu 2.1.0 \f[V]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 +\f[V]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 @@ -110,18 +124,18 @@ 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 +\f[V]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 +\f[V]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 +\f[V]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]). +Preallocation mode (allowed values: \f[V]off\f[R] (default), +\f[V]metadata\f[R], \f[V]falloc\f[R], \f[V]full\f[R]). An image with preallocated metadata is initially larger but can improve performance when the image needs to grow. .PP @@ -129,27 +143,27 @@ 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] +\f[V]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] +\f[V]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] +\f[V]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 +All File Sharing options will only expose \f[V]\[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 +If \f[V]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 @@ -160,6 +174,21 @@ You can install the minimal Samba components on Ubuntu using: sudo apt install --no-install-recommends samba \f[R] .fi +.PP +If everything is set up correctly, the \f[V]smbd\f[R] address will be +printed when the virtual machine is started. +For example: +.IP +.nf +\f[C] + - smbd: On guest: smb://10.0.2.4/qemu +\f[R] +.fi +.PP +If using a Windows guest, right-click on \[lq]This PC\[rq], click +\[lq]Add a network location\[rq], and paste this address, removing +\f[V]smb:\f[R] and replacing forward slashes with backslashes (in this +example \f[V]\[rs]\[rs]10.0.2.4\[rs]qemu\f[R]). .SS SPICE WebDAV \[u1F427] \[u1FA9F] .IP \[bu] 2 TBD @@ -171,7 +200,7 @@ TBD 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] +\f[V]port_forwards=(\[dq]8123:8123\[dq] \[dq]8888:80\[dq])\f[R] .PP In the example above: .IP \[bu] 2 @@ -183,7 +212,7 @@ Port 8888 on the host is forwarded to port 80 on the guest. 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] +\f[V]bridge=\[dq]br0\[dq]\f[R] .SH USB redirection .PP Quickemu supports USB redirection via SPICE pass-through and host @@ -191,9 +220,9 @@ 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 +any elevated permission, start Quickemu with \f[V]--display spice\f[R] +and then select \f[V]Input\f[R] -> +\f[V]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 @@ -204,7 +233,7 @@ Using SPICE is preferred, see above. 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] +\f[V]usb_devices=(\[dq]046d:082d\[dq] \[dq]046d:085e\[dq])\f[R] .PP In the example above: .IP \[bu] 2 @@ -214,7 +243,7 @@ to the guest. 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 +If the USB devices are not writable, \f[V]quickemu\f[R] will display the appropriate commands to modify the USB device(s) access permissions, like this: .IP @@ -230,8 +259,8 @@ like this: .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 +Just add \f[V]tpm=\[dq]on\[dq]\f[R] to your VM configuration. +\f[V]quickget\f[R] will automatically add this line to Windows 11 virtual machines. .SH AUTHORS .PP diff --git a/docs/quickemu_conf.1.md b/docs/quickemu_conf.1.md index a978739..8ff9ba7 100644 --- a/docs/quickemu_conf.1.md +++ b/docs/quickemu_conf.1.md @@ -1,19 +1,17 @@ --- author: Martin Wimpress -date: 'February 20, 2022' -footer: quickemu\_conf +date: July 30, 2022 +footer: quickemu_conf header: Quickemu Configuration Manual section: 1 -title: QUICKEMU\_CONF +title: QUICKEMU_CONF --- -NAME -==== +# NAME -quickemu\_conf - Options and parameters in the quickemu \.conf +quickemu_conf - Options and parameters in the quickemu \.conf -DESCRIPTION -=========== +# DESCRIPTION **quickemu** will create and run highly optimised desktop virtual machines for Linux, macOS and Windows. It uses sensible defaults, but @@ -21,12 +19,11 @@ 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 -======= +# OPTIONS These are the options and defaults for the \.conf file -``` {.bash} +``` bash # Lowercase variables are used in the VM config file only boot="efi" bridge="" @@ -47,10 +44,9 @@ tpm="off" usb_devices=() ``` -EXAMPLES -======== +# EXAMPLES -``` {.bash} +``` bash guest_os="linux" disk_img="debian-bullseye/disk.qcow2" iso="debian-bullseye/firmware-11.0.0-amd64-DVD-1.iso" @@ -58,7 +54,7 @@ iso="debian-bullseye/firmware-11.0.0-amd64-DVD-1.iso" The default macOS configuration looks like this: -``` {.bash} +``` bash guest_os="macos" img="macos-catalina/RecoveryImage.img" disk_img="macos-catalina/disk.qcow2" @@ -75,7 +71,7 @@ macos_release="catalina" The default Windows 11 configuration looks like this: -``` {.bash} +``` bash guest_os="windows" disk_img="windows-11/disk.qcow2" iso="windows-11/Win11_EnglishInternational_x64.iso" @@ -88,8 +84,7 @@ tpm="on" - `tpm="on"` instructs `quickemu` to create a software emulated TPM device using `swtpm`. -BIOS and EFI -============ +# 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 @@ -97,8 +92,7 @@ configuration to enable legacy BIOS. - `boot="legacy"` - Enable Legacy BIOS boot -Tuning CPU cores, RAM & disks -============================= +# 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 @@ -113,8 +107,7 @@ Add additional lines to your virtual machine configuration: - `disk_size="16G"` - Specify the size of the virtual disk allocated to the VM -Disk preallocation ------------------- +## Disk preallocation Preallocation mode (allowed values: `off` (default), `metadata`, `falloc`, `full`). An image with preallocated metadata is initially @@ -126,16 +119,14 @@ configuration. - `preallocation="metadata"` -CD-ROM disks ------------- +## 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 ------------- +## 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 @@ -143,14 +134,12 @@ to the VM configuration: - `floppy="/path/to/floppy.img"` -File Sharing -============ +# File Sharing All File Sharing options will only expose `~/Public` (or localised variations) for the current user to the guest VMs. -Samba 🐧 🍏 🪟 ------------ +## 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 @@ -158,22 +147,28 @@ the guest. You can install the minimal Samba components on Ubuntu using: -``` {.bash} +``` bash sudo apt install --no-install-recommends samba ``` -SPICE WebDAV 🐧 🪟 ----------------- +If everything is set up correctly, the `smbd` address will be printed +when the virtual machine is started. For example: + + - smbd: On guest: smb://10.0.2.4/qemu + +If using a Windows guest, right-click on "This PC", click "Add a network +location", and paste this address, removing `smb:` and replacing forward +slashes with backslashes (in this example `\\10.0.2.4\qemu`). + +## SPICE WebDAV 🐧 🪟 - TBD -VirtIO-9P 🐧 🍏 -------------- +## VirtIO-9P 🐧 🍏 - TBD -Network port forwarding -======================= +# Network port forwarding Add an additional line to your virtual machine configuration. For example: @@ -185,30 +180,26 @@ 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 -================== +# Bridged networking Connect your virtual machine to a preconfigured network bridge. Add an additional line to your virtual machine configuration - `bridge="br0"` -USB redirection -=============== +# USB redirection Quickemu supports USB redirection via SPICE pass-through and host pass-through. -SPICE redirection (recommended) -------------------------------- +## 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** ------------------------------------- +## 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 @@ -221,9 +212,9 @@ example: In the example above: -- The USB device with vendor\_id 046d and product\_id 082d will be +- 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 +- 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 @@ -235,27 +226,23 @@ like this: sudo chown -v root:user /dev/bus/usb/001/005 ERROR! USB permission changes are required 👆 -TPM -=== +# 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 -======= +# AUTHORS Written by Martin Wimpress. -BUGS -==== +# BUGS Submit bug reports online at: -SEE ALSO -======== +# SEE ALSO Full sources at: diff --git a/docs/quickget.1 b/docs/quickget.1 index 2ee7927..3bcc359 100644 --- a/docs/quickget.1 +++ b/docs/quickget.1 @@ -1,6 +1,20 @@ -.\" Automatically generated by Pandoc 2.9.2.1 +.\" Automatically generated by Pandoc 2.18 .\" -.TH "QUICKGET" "1" "February 20, 2022" "quickget" "Quickget User Manual" +.\" 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" "July 30, 2022" "quickget" "Quickget User Manual" .hy .SH NAME .PP @@ -12,7 +26,7 @@ quickget - download and prepare materials for building a quickemu VM .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 +configuration for \f[V]quickemu\f[R] to use to build and run .SH OPTIONS .TP \f[B]version | -version | \[en]version\f[R] @@ -29,13 +43,13 @@ 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 +\f[V]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 +quickget ubuntu 22.04 +quickemu --vm ubuntu-22.04.conf \f[R] .fi .IP \[bu] 2 @@ -44,24 +58,24 @@ Complete the installation as normal. Post-install: .RS 2 .IP \[bu] 2 -Install the SPICE agent (\f[C]spice-vdagent\f[R]) to enable copy/paste +Install the SPICE agent (\f[V]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] +\f[V]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 +Install the SPICE WebDAV agent (\f[V]spice-webdavd\f[R]) to enable file sharing. .RS 2 .IP \[bu] 2 -\f[C]sudo apt install spice-webdavd\f[R] +\f[V]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. +\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] @@ -70,106 +84,116 @@ quickemu --vm ubuntu-devel.conf \f[R] .fi .PP -You can run \f[C]quickget ubuntu devel\f[R] to refresh your daily +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[C]ubuntu\f[R] with your preferred flavour. +\f[V]ubuntu\f[R] with your preferred flavour. .IP \[bu] 2 -\f[C]kubuntu\f[R] (Kubuntu) +\f[V]kubuntu\f[R] (Kubuntu) .IP \[bu] 2 -\f[C]lubuntu\f[R] (Lubuntu) +\f[V]lubuntu\f[R] (Lubuntu) .IP \[bu] 2 -\f[C]ubuntu-budgie\f[R] (Ubuntu Budgie) +\f[V]ubuntu-budgie\f[R] (Ubuntu Budgie) .IP \[bu] 2 -\f[C]ubuntukylin\f[R] (Ubuntu Kylin) +\f[V]ubuntukylin\f[R] (Ubuntu Kylin) .IP \[bu] 2 -\f[C]ubuntu-mate\f[R] (Ubuntu MATE) +\f[V]ubuntu-mate\f[R] (Ubuntu MATE) .IP \[bu] 2 -\f[C]ubuntustudio\f[R] (Ubuntu Studio) +\f[V]ubuntustudio\f[R] (Ubuntu Studio) .IP \[bu] 2 -\f[C]ubuntu\f[R] (Ubuntu) +\f[V]ubuntu\f[R] (Ubuntu) .IP \[bu] 2 -\f[C]xubuntu\f[R] (Xubuntu) +\f[V]xubuntu\f[R] (Xubuntu) .SS Other Operating Systems .PP -\f[C]quickget\f[R] also supports: +\f[V]quickget\f[R] also supports: .IP \[bu] 2 -\f[C]alma\f[R] (Alma Linux) +\f[V]alma\f[R] (Alma Linux) .IP \[bu] 2 -\f[C]alpine\f[R] (Alpine Linux) +\f[V]alpine\f[R] (Alpine Linux) .IP \[bu] 2 -\f[C]android\f[R] (Android x86) +\f[V]android\f[R] (Android x86) .IP \[bu] 2 -\f[C]archlinux\f[R] (Arch Linux) +\f[V]archlinux\f[R] (Arch Linux) .IP \[bu] 2 -\f[C]arcolinux\f[R] (Arco Linux) +\f[V]arcolinux\f[R] (Arco Linux) .IP \[bu] 2 -\f[C]cachyos\f[R] (CachyOS) +\f[V]batocera\f[R] (Batocera) .IP \[bu] 2 -\f[C]debian\f[R] (Debian) +\f[V]cachyos\f[R] (CachyOS) .IP \[bu] 2 -\f[C]devuan\f[R] (Devuan) +\f[V]centos-stream\f[R] (CentOS Stream) .IP \[bu] 2 -\f[C]dragonflybsd\f[R] (DragonFlyBSD) +\f[V]debian\f[R] (Debian) .IP \[bu] 2 -\f[C]elementary\f[R] (elementary OS) +\f[V]deepin\f[R] (Deepin) .IP \[bu] 2 -\f[C]fedora\f[R] (Fedora) +\f[V]devuan\f[R] (Devuan) .IP \[bu] 2 -\f[C]freebsd\f[R] (FreeBSD) +\f[V]dragonflybsd\f[R] (DragonFlyBSD) .IP \[bu] 2 -\f[C]freedos\f[R] (FreeDOS) +\f[V]elementary\f[R] (elementary OS) .IP \[bu] 2 -\f[C]garuda\f[R] (Garuda Linux) +\f[V]endeavouros\f[R] (EndeavourOS) .IP \[bu] 2 -\f[C]gentoo\f[R] (Gentoo) +\f[V]fedora\f[R] (Fedora) .IP \[bu] 2 -\f[C]ghostbsd\f[R] (GhostBSD) +\f[V]freebsd\f[R] (FreeBSD) .IP \[bu] 2 -\f[C]haiku\f[R] (Haiku) +\f[V]freedos\f[R] (FreeDOS) .IP \[bu] 2 -\f[C]kali\f[R] (Kali) +\f[V]garuda\f[R] (Garuda Linux) .IP \[bu] 2 -\f[C]kdeneon\f[R] (KDE Neon) +\f[V]gentoo\f[R] (Gentoo) .IP \[bu] 2 -\f[C]kolibrios\f[R] (KolibriOS) +\f[V]ghostbsd\f[R] (GhostBSD) .IP \[bu] 2 -\f[C]linuxmint\f[R] (Linux Mint) +\f[V]haiku\f[R] (Haiku) .IP \[bu] 2 -\f[C]manjaro\f[R] (Manjaro) +\f[V]kali\f[R] (Kali) .IP \[bu] 2 -\f[C]mxlinux\f[R] (MX Linux) +\f[V]kdeneon\f[R] (KDE Neon) .IP \[bu] 2 -\f[C]netboot\f[R] (netboot.xyz) +\f[V]kolibrios\f[R] (KolibriOS) .IP \[bu] 2 -\f[C]netbsd\f[R] (NetBSD) +\f[V]linuxmint\f[R] (Linux Mint) .IP \[bu] 2 -\f[C]nixos\f[R] (NixOS) +\f[V]lmde\f[R] (Linux Mint Debian Edition) .IP \[bu] 2 -\f[C]openbsd\f[R] (OpenBSD) +\f[V]manjaro\f[R] (Manjaro) .IP \[bu] 2 -\f[C]opensuse\f[R] (openSUSE) +\f[V]mxlinux\f[R] (MX Linux) .IP \[bu] 2 -\f[C]oraclelinux\f[R] (Oracle Linux) +\f[V]netboot\f[R] (netboot.xyz) .IP \[bu] 2 -\f[C]popos\f[R] (Pop!_OS) +\f[V]netbsd\f[R] (NetBSD) .IP \[bu] 2 -\f[C]regolith\f[R] (Regolith Linux) +\f[V]nixos\f[R] (NixOS) .IP \[bu] 2 -\f[C]rockylinux\f[R] (Rocky Linux) +\f[V]openbsd\f[R] (OpenBSD) .IP \[bu] 2 -\f[C]slackware\f[R] (Slackware) +\f[V]opensuse\f[R] (openSUSE) .IP \[bu] 2 -\f[C]solus\f[R] (Solus) +\f[V]oraclelinux\f[R] (Oracle Linux) .IP \[bu] 2 -\f[C]tails\f[R] (Tails) +\f[V]popos\f[R] (Pop!_OS) .IP \[bu] 2 -\f[C]void\f[R] (Void Linux) +\f[V]regolith\f[R] (Regolith Linux) .IP \[bu] 2 -\f[C]zorin\f[R] (Zorin OS) +\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. @@ -177,7 +201,7 @@ configuration. 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] +\f[V]debian-bullseye.conf\f[R] .IP .nf \f[C] @@ -187,7 +211,7 @@ 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: +Use \f[V]quickemu\f[R] to start the virtual machine: .IP .nf \f[C] @@ -200,15 +224,15 @@ Complete the installation as normal. Post-install: .RS 2 .IP \[bu] 2 -Install the SPICE agent (\f[C]spice-vdagent\f[R]) to enable copy/paste +Install the SPICE agent (\f[V]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 +Install the SPICE WebDAV agent (\f[V]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 +\f[V]quickget\f[R] automatically downloads a macOS recovery image and creates a virtual machine configuration. .IP .nf @@ -218,8 +242,8 @@ 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. +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 @@ -232,19 +256,19 @@ Click \f[B]Disk Utility\f[R] and \f[B]Continue\f[R] 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 +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[C]QEMU HARDDISK Media\f[R] (\[ti]103.08GB) from the list and +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[C]Name:\f[R] for the disk and click \f[B]Erase\f[R]. +Enter a \f[V]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 @@ -278,10 +302,10 @@ 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 +\f[V]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 +\f[V]macos_release=\[dq]catalina\[dq]\f[R] instructs Quickemu to optimise for a particular macOS release. .RS 2 .IP \[bu] 2 @@ -309,7 +333,7 @@ Big Sur Monterey .RE .IP \[bu] 2 -\f[C]quickemu\f[R] will automatically download the required +\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 @@ -322,11 +346,11 @@ 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 +VirtIO \f[V]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]. +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. @@ -355,7 +379,7 @@ webdavd (https://gitlab.gnome.org/GNOME/phodav/-/merge_requests/24). 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 +\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 @@ -374,7 +398,7 @@ Complete the installation as you normally would. 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 +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 @@ -393,17 +417,18 @@ 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[C]guest_os=\[dq]windows\[dq]\f[R] instructs \f[C]quickemu\f[R] to +\f[V]guest_os=\[dq]windows\[dq]\f[R] instructs \f[V]quickemu\f[R] to optimise for Windows. .IP \[bu] 2 -\f[C]fixed_iso=\f[R] specifies the ISO image that provides VirtIO +\f[V]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]. +\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. diff --git a/docs/quickget.1.md b/docs/quickget.1.md index fa7939b..e34b73a 100644 --- a/docs/quickget.1.md +++ b/docs/quickget.1.md @@ -1,35 +1,31 @@ --- author: Martin Wimpress -date: 'February 20, 2022' +date: July 30, 2022 footer: quickget header: Quickget User Manual section: 1 title: QUICKGET --- -NAME -==== +# NAME quickget - download and prepare materials for building a quickemu VM -SYNOPSIS -======== +# SYNOPSIS **quickget** \[*os*\] \[*release*\] \[*edition*\] \| \[*OPTION*\]\* -DESCRIPTION -=========== +# DESCRIPTION **quickget** will download the requisite materials and prepare a configuration for `quickemu` to use to build and run -OPTIONS -======= +# OPTIONS **version \| -version \| --version** : show version (from Quickemu) -**list \| list\_csv \| list\_json** +**list \| list_csv \| list_json** : provide a csv list of all supported guest OSes, versions and variants. @@ -39,18 +35,16 @@ OPTIONS script will exit. Editions may not apply and will be defaulted if not provided. -NOTES -===== +# NOTES -Ubuntu Guest ------------- +## 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 +``` bash +quickget ubuntu 22.04 +quickemu --vm ubuntu-22.04.conf ``` - Complete the installation as normal. @@ -67,7 +61,7 @@ quickemu --vm ubuntu-20.04.conf `quickget` can also download/refresh devel images via `zsync` for Ubuntu developers and testers. -``` {.bash} +``` bash quickget ubuntu devel quickemu --vm ubuntu-devel.conf ``` @@ -90,8 +84,7 @@ with your preferred flavour. - `ubuntu` (Ubuntu) - `xubuntu` (Xubuntu) -Other Operating Systems ------------------------ +## Other Operating Systems `quickget` also supports: @@ -100,11 +93,15 @@ Other Operating Systems - `android` (Android x86) - `archlinux` (Arch Linux) - `arcolinux` (Arco Linux) +- `batocera` (Batocera) - `cachyos` (CachyOS) +- `centos-stream` (CentOS Stream) - `debian` (Debian) +- `deepin` (Deepin) - `devuan` (Devuan) - `dragonflybsd` (DragonFlyBSD) - `elementary` (elementary OS) +- `endeavouros` (EndeavourOS) - `fedora` (Fedora) - `freebsd` (FreeBSD) - `freedos` (FreeDOS) @@ -116,6 +113,7 @@ Other Operating Systems - `kdeneon` (KDE Neon) - `kolibrios` (KolibriOS) - `linuxmint` (Linux Mint) +- `lmde` (Linux Mint Debian Edition) - `manjaro` (Manjaro) - `mxlinux` (MX Linux) - `netboot` (netboot.xyz) @@ -139,7 +137,7 @@ configuration. - Download a .iso image of a Linux distribution - Create a VM configuration file; for example `debian-bullseye.conf` -``` {.bash} +``` bash guest_os="linux" disk_img="debian-bullseye/disk.qcow2" iso="debian-bullseye/firmware-11.0.0-amd64-DVD-1.iso" @@ -147,7 +145,7 @@ iso="debian-bullseye/firmware-11.0.0-amd64-DVD-1.iso" - Use `quickemu` to start the virtual machine: -``` {.bash} +``` bash quickemu --vm debian-bullseye.conf ``` @@ -158,13 +156,12 @@ quickemu --vm debian-bullseye.conf - Install the SPICE WebDAV agent (`spice-webdavd`) to enable file sharing. -macOS Guest ------------ +## macOS Guest `quickget` automatically downloads a macOS recovery image and creates a virtual machine configuration. -``` {.bash} +``` bash quickget macos catalina quickemu --vm macos-catalina.conf ``` @@ -194,7 +191,7 @@ supported. The default macOS configuration looks like this: -``` {.bash} +``` bash guest_os="macos" img="macos-catalina/RecoveryImage.img" disk_img="macos-catalina/disk.qcow2" @@ -245,8 +242,7 @@ There are some considerations when running macOS via Quickemu. 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 ---------------------------- +## 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 @@ -256,7 +252,7 @@ with the [VirtIO drivers for Windows](https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/) and creates a virtual machine configuration. -``` {.bash} +``` bash quickget windows 11 quickemu --vm windows-11.conf ``` @@ -270,18 +266,19 @@ By default `quickget` will download the *"English International"* release, but you can optionally specify one of the supported languages: For example: -``` {.bash} +``` bash quickget windows 11 "Chinese (Traditional)" ``` The default Windows 11 configuration looks like this: -``` {.bash} +``` 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" +secureboot="on" ``` - `guest_os="windows"` instructs `quickemu` to optimise for Windows. @@ -289,20 +286,17 @@ tpm="on" - `tpm="on"` instructs `quickemu` to create a software emulated TPM device using `swtpm`. -AUTHORS -======= +# AUTHORS Written by Martin Wimpress. -BUGS -==== +# BUGS Submit bug reports online at: -SEE ALSO -======== +# SEE ALSO Full sources at: -quickemu(1), quickemu\_conf(1), quickgui(1) +quickemu(1), quickemu_conf(1), quickgui(1)