AIR/quickemu
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

updated for LTS release

Browse Source
This commit is contained in:
Phil Clifford 2022-04-29 01:35:54 +01:00
parent 187da46c3b
commit dd4317997f
7 changed files with 441 additions and 467 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

177
README.md
View File

@ -8,17 +8,16 @@
<div align="center"><img src=".github/screenshot.png" alt="Quickemu Screenshot" /></div>
<p align="center">Made with 💝 for <img src=".github/tux.png" align="top" width="18" /></p>
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,9 @@ Requirements
- [zsync](http://zsync.moria.org.uk/)
- [unzip](http://www.info-zip.org/UnZip.html)
Usage
=====
# Usage
Graphical User Interfaces
-------------------------
## Graphical User Interfaces
While `quickemu` and `quickget` are designed for the terminal, a
graphical user interface is also available:
@ -112,33 +107,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 +152,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 +176,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 +199,11 @@ with your preferred flavour.
- `ubuntu` (Ubuntu)
- `xubuntu` (Xubuntu)
Other Operating Systems
-----------------------
## Other Operating Systems
`quickget` also supports:
## Other Operating Systems
`quickget` also supports:
@ -257,7 +251,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 +259,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 +270,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 +305,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 +356,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 +366,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 +380,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"
@ -407,8 +399,7 @@ tpm="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:
@ -420,49 +411,46 @@ 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
```
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
@ -470,8 +458,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
@ -486,8 +473,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
@ -499,16 +485,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
@ -516,14 +500,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
@ -531,22 +513,19 @@ the guest.
You can install the minimal Samba components on Ubuntu using:
``` {.bash}
``` bash
sudo apt install --no-install-recommends samba
```
SPICE WebDAV 🐧 🪟
----------------
## 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:
@ -558,30 +537,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
@ -594,9 +569,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
@ -608,20 +583,19 @@ 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}
``` bash
Usage
quickemu --vm ubuntu.conf
@ -644,19 +618,17 @@ You can also pass optional parameters
```
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.
@ -677,13 +649,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
```
@ -692,7 +664,7 @@ The first number is what needs to be passed to the `--screen` option.
For example:
``` {.bash}
``` bash
quickemu --vm vm.conf --screen 0
```
@ -701,8 +673,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.

208
docs/quickemu.1
View File

@ -1,5 +1,19 @@
.\" Automatically generated by Pandoc 2.9.2.1
.\" Automatically generated by Pandoc 2.18
.\"
.\" 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" "February 20, 2022" "quickemu" "Quickemu User Manual"
.hy
.SH NAME
@ -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
@ -184,7 +198,7 @@ unzip (http://www.info-zip.org/UnZip.html)
.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 +220,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 +235,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 +261,109 @@ 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:
.SS Other Operating Systems
.PP
\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]cachyos\f[R] (CachyOS)
.IP \[bu] 2
\f[C]debian\f[R] (Debian)
\f[V]debian\f[R] (Debian)
.IP \[bu] 2
\f[C]devuan\f[R] (Devuan)
\f[V]devuan\f[R] (Devuan)
.IP \[bu] 2
\f[C]dragonflybsd\f[R] (DragonFlyBSD)
\f[V]dragonflybsd\f[R] (DragonFlyBSD)
.IP \[bu] 2
\f[C]elementary\f[R] (elementary OS)
\f[V]elementary\f[R] (elementary OS)
.IP \[bu] 2
\f[C]fedora\f[R] (Fedora)
\f[V]fedora\f[R] (Fedora)
.IP \[bu] 2
\f[C]freebsd\f[R] (FreeBSD)
\f[V]freebsd\f[R] (FreeBSD)
.IP \[bu] 2
\f[C]freedos\f[R] (FreeDOS)
\f[V]freedos\f[R] (FreeDOS)
.IP \[bu] 2
\f[C]garuda\f[R] (Garuda Linux)
\f[V]garuda\f[R] (Garuda Linux)
.IP \[bu] 2
\f[C]gentoo\f[R] (Gentoo)
\f[V]gentoo\f[R] (Gentoo)
.IP \[bu] 2
\f[C]ghostbsd\f[R] (GhostBSD)
\f[V]ghostbsd\f[R] (GhostBSD)
.IP \[bu] 2
\f[C]haiku\f[R] (Haiku)
\f[V]haiku\f[R] (Haiku)
.IP \[bu] 2
\f[C]kali\f[R] (Kali)
\f[V]kali\f[R] (Kali)
.IP \[bu] 2
\f[C]kdeneon\f[R] (KDE Neon)
\f[V]kdeneon\f[R] (KDE Neon)
.IP \[bu] 2
\f[C]kolibrios\f[R] (KolibriOS)
\f[V]kolibrios\f[R] (KolibriOS)
.IP \[bu] 2
\f[C]linuxmint\f[R] (Linux Mint)
\f[V]linuxmint\f[R] (Linux Mint)
.IP \[bu] 2
\f[C]manjaro\f[R] (Manjaro)
\f[V]manjaro\f[R] (Manjaro)
.IP \[bu] 2
\f[C]mxlinux\f[R] (MX Linux)
\f[V]mxlinux\f[R] (MX Linux)
.IP \[bu] 2
\f[C]netboot\f[R] (netboot.xyz)
\f[V]netboot\f[R] (netboot.xyz)
.IP \[bu] 2
\f[C]netbsd\f[R] (NetBSD)
\f[V]netbsd\f[R] (NetBSD)
.IP \[bu] 2
\f[C]nixos\f[R] (NixOS)
\f[V]nixos\f[R] (NixOS)
.IP \[bu] 2
\f[C]openbsd\f[R] (OpenBSD)
\f[V]openbsd\f[R] (OpenBSD)
.IP \[bu] 2
\f[C]opensuse\f[R] (openSUSE)
\f[V]opensuse\f[R] (openSUSE)
.IP \[bu] 2
\f[C]oraclelinux\f[R] (Oracle Linux)
\f[V]oraclelinux\f[R] (Oracle Linux)
.IP \[bu] 2
\f[C]popos\f[R] (Pop!_OS)
\f[V]popos\f[R] (Pop!_OS)
.IP \[bu] 2
\f[C]regolith\f[R] (Regolith Linux)
\f[V]regolith\f[R] (Regolith Linux)
.IP \[bu] 2
\f[C]rockylinux\f[R] (Rocky Linux)
\f[V]rockylinux\f[R] (Rocky Linux)
.IP \[bu] 2
\f[C]slackware\f[R] (Slackware)
\f[V]slackware\f[R] (Slackware)
.IP \[bu] 2
\f[C]solus\f[R] (Solus)
\f[V]solus\f[R] (Solus)
.IP \[bu] 2
\f[C]tails\f[R] (Tails)
\f[V]tails\f[R] (Tails)
.IP \[bu] 2
\f[C]void\f[R] (Void Linux)
\f[V]void\f[R] (Void Linux)
.IP \[bu] 2
\f[C]zorin\f[R] (Zorin OS)
\f[V]zorin\f[R] (Zorin OS)
.PP
Or you can download a Linux image and manually create a VM
configuration.
@ -354,7 +371,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 +381,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 +394,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 +412,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 +426,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 +472,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 +503,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 +516,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 +549,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 +568,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
@ -573,14 +590,14 @@ 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 All the options
.PP
Here are the usage instructions:
@ -588,6 +605,7 @@ Here are the usage instructions:
.nf
\f[C]
Usage
quickemu --vm ubuntu.conf
@ -612,32 +630,32 @@ You can also pass optional parameters
.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 +677,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 +690,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

118
docs/quickemu.1.md
View File

@ -1,30 +1,26 @@
---
author: Martin Wimpress
date: 'February 20, 2022'
date: February 20, 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,9 @@ Requirements
- [zsync](http://zsync.moria.org.uk/)
- [unzip](http://www.info-zip.org/UnZip.html)
Usage
=====
# Usage
Graphical User Interfaces
-------------------------
## Graphical User Interfaces
While `quickemu` and `quickget` are designed for the terminal, a
graphical user interface is also available:
@ -180,21 +170,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 +200,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 +223,11 @@ with your preferred flavour.
- `ubuntu` (Ubuntu)
- `xubuntu` (Xubuntu)
Other Operating Systems
-----------------------
## Other Operating Systems
`quickget` also supports:
## Other Operating Systems
`quickget` also supports:
@ -283,7 +275,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 +283,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 +294,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 +329,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 +380,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 +390,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,13 +404,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"
@ -433,12 +423,12 @@ 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}
``` bash
Usage
quickemu --vm ubuntu.conf
@ -461,19 +451,17 @@ You can also pass optional parameters
```
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.
@ -494,13 +482,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 +497,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 +506,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 +543,17 @@ Useful reference that assisted the development of Quickemu.
- <https://superuser.com/questions/628169/how-to-share-a-directory-with-the-host-without-networking-in-qemu>
- <https://virtio-fs.gitlab.io/>
AUTHORS
=======
# AUTHORS
Written by Martin Wimpress.
BUGS
====
# BUGS
Submit bug reports online at:
<https://github.com/quickemu-project/quickemu/issues>
SEE ALSO
========
# SEE ALSO
Full sources at: <https://github.com/quickemu-project/quickemu>
quickemu\_conf(1), quickget(1), quickgui(1)
quickemu_conf(1), quickget(1), quickgui(1)

70
docs/quickemu_conf.1
View File

@ -1,5 +1,19 @@
.\" Automatically generated by Pandoc 2.9.2.1
.\" Automatically generated by Pandoc 2.18
.\"
.\" 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" "February 20, 2022" "quickemu_conf" "Quickemu Configuration Manual"
.hy
.SH NAME
@ -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
@ -171,7 +185,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 +197,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 +205,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 +218,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 +228,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 +244,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

88
docs/quickemu_conf.1.md
View File

@ -1,19 +1,17 @@
---
author: Martin Wimpress
date: 'February 20, 2022'
footer: quickemu\_conf
date: February 20, 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 \<vm\>.conf
quickemu_conf - Options and parameters in the quickemu \<vm\>.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 \<vm\>.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,19 @@ the guest.
You can install the minimal Samba components on Ubuntu using:
``` {.bash}
``` bash
sudo apt install --no-install-recommends samba
```
SPICE WebDAV 🐧 🪟
----------------
## 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 +171,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 +203,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 +217,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:
<https://github.com/quickemu-project/quickemu/issues>
SEE ALSO
========
# SEE ALSO
Full sources at: <https://github.com/quickemu-project/quickemu>

179
docs/quickget.1
View File

@ -1,5 +1,19 @@
.\" Automatically generated by Pandoc 2.9.2.1
.\" Automatically generated by Pandoc 2.18
.\"
.\" 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" "February 20, 2022" "quickget" "Quickget User Manual"
.hy
.SH NAME
@ -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,109 @@ 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:
.SS Other Operating Systems
.PP
\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]cachyos\f[R] (CachyOS)
.IP \[bu] 2
\f[C]debian\f[R] (Debian)
\f[V]debian\f[R] (Debian)
.IP \[bu] 2
\f[C]devuan\f[R] (Devuan)
\f[V]devuan\f[R] (Devuan)
.IP \[bu] 2
\f[C]dragonflybsd\f[R] (DragonFlyBSD)
\f[V]dragonflybsd\f[R] (DragonFlyBSD)
.IP \[bu] 2
\f[C]elementary\f[R] (elementary OS)
\f[V]elementary\f[R] (elementary OS)
.IP \[bu] 2
\f[C]fedora\f[R] (Fedora)
\f[V]fedora\f[R] (Fedora)
.IP \[bu] 2
\f[C]freebsd\f[R] (FreeBSD)
\f[V]freebsd\f[R] (FreeBSD)
.IP \[bu] 2
\f[C]freedos\f[R] (FreeDOS)
\f[V]freedos\f[R] (FreeDOS)
.IP \[bu] 2
\f[C]garuda\f[R] (Garuda Linux)
\f[V]garuda\f[R] (Garuda Linux)
.IP \[bu] 2
\f[C]gentoo\f[R] (Gentoo)
\f[V]gentoo\f[R] (Gentoo)
.IP \[bu] 2
\f[C]ghostbsd\f[R] (GhostBSD)
\f[V]ghostbsd\f[R] (GhostBSD)
.IP \[bu] 2
\f[C]haiku\f[R] (Haiku)
\f[V]haiku\f[R] (Haiku)
.IP \[bu] 2
\f[C]kali\f[R] (Kali)
\f[V]kali\f[R] (Kali)
.IP \[bu] 2
\f[C]kdeneon\f[R] (KDE Neon)
\f[V]kdeneon\f[R] (KDE Neon)
.IP \[bu] 2
\f[C]kolibrios\f[R] (KolibriOS)
\f[V]kolibrios\f[R] (KolibriOS)
.IP \[bu] 2
\f[C]linuxmint\f[R] (Linux Mint)
\f[V]linuxmint\f[R] (Linux Mint)
.IP \[bu] 2
\f[C]manjaro\f[R] (Manjaro)
\f[V]manjaro\f[R] (Manjaro)
.IP \[bu] 2
\f[C]mxlinux\f[R] (MX Linux)
\f[V]mxlinux\f[R] (MX Linux)
.IP \[bu] 2
\f[C]netboot\f[R] (netboot.xyz)
\f[V]netboot\f[R] (netboot.xyz)
.IP \[bu] 2
\f[C]netbsd\f[R] (NetBSD)
\f[V]netbsd\f[R] (NetBSD)
.IP \[bu] 2
\f[C]nixos\f[R] (NixOS)
\f[V]nixos\f[R] (NixOS)
.IP \[bu] 2
\f[C]openbsd\f[R] (OpenBSD)
\f[V]openbsd\f[R] (OpenBSD)
.IP \[bu] 2
\f[C]opensuse\f[R] (openSUSE)
\f[V]opensuse\f[R] (openSUSE)
.IP \[bu] 2
\f[C]oraclelinux\f[R] (Oracle Linux)
\f[V]oraclelinux\f[R] (Oracle Linux)
.IP \[bu] 2
\f[C]popos\f[R] (Pop!_OS)
\f[V]popos\f[R] (Pop!_OS)
.IP \[bu] 2
\f[C]regolith\f[R] (Regolith Linux)
\f[V]regolith\f[R] (Regolith Linux)
.IP \[bu] 2
\f[C]rockylinux\f[R] (Rocky Linux)
\f[V]rockylinux\f[R] (Rocky Linux)
.IP \[bu] 2
\f[C]slackware\f[R] (Slackware)
\f[V]slackware\f[R] (Slackware)
.IP \[bu] 2
\f[C]solus\f[R] (Solus)
\f[V]solus\f[R] (Solus)
.IP \[bu] 2
\f[C]tails\f[R] (Tails)
\f[V]tails\f[R] (Tails)
.IP \[bu] 2
\f[C]void\f[R] (Void Linux)
\f[V]void\f[R] (Void Linux)
.IP \[bu] 2
\f[C]zorin\f[R] (Zorin OS)
\f[V]zorin\f[R] (Zorin OS)
.PP
Or you can download a Linux image and manually create a VM
configuration.
@ -177,7 +194,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 +204,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 +217,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 +235,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 +249,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 +295,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 +326,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 +339,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 +372,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 +391,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
@ -396,14 +413,14 @@ 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 AUTHORS
.PP
Written by Martin Wimpress.

68
docs/quickget.1.md
View File

@ -1,35 +1,31 @@
---
author: Martin Wimpress
date: 'February 20, 2022'
date: February 20, 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,11 @@ with your preferred flavour.
- `ubuntu` (Ubuntu)
- `xubuntu` (Xubuntu)
Other Operating Systems
-----------------------
## Other Operating Systems
`quickget` also supports:
## Other Operating Systems
`quickget` also supports:
@ -139,7 +136,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 +144,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 +155,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 +190,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 +241,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 +251,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,13 +265,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"
@ -289,20 +284,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:
<https://github.com/quickemu-project/quickemu/issues>
SEE ALSO
========
# SEE ALSO
Full sources at: <https://github.com/quickemu-project/quickemu>
quickemu(1), quickemu\_conf(1), quickgui(1)
quickemu(1), quickemu_conf(1), quickgui(1)