docs: add more nixos info (#171)

author: egasimus <adam@hack.bg>
This commit is contained in:
zenobit 2024-04-09 01:06:50 +02:00 committed by Martin Wimpress
parent 68e23b41a7
commit 51f17bb5ef
1 changed files with 207 additions and 138 deletions

345
README.md
View File

@ -1,31 +1,75 @@
<h1 align="center">
<img src=".github/logo.png" alt="Quickemu" width="256" />
<br />
Quickemu
</h1>
<div align="center">
<p align="center"><b>Quickly create and run optimised Windows, macOS and Linux desktop virtual machines.</b></p>
<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>
<img src=".github/logo.png" alt="Quickemu" width="256" />
## Introduction
# Quickemu
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:
**Quickly create and run optimised Windows, macOS and Linux desktop virtual machines:**
``` bash
</div>
```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
Linux distributions where the virtual machine configurations can be
stored anywhere, such as external USB storage or your home directory,
<div align="center">
<img src=".github/screenshot.png" alt="Quickemu Screenshot" />
**Made with 💝 for <img src=".github/tux.png" align="top" width="24" />.**
Quickemu is available in the repositories of the following distros
(packaging status by [Repology.org](https://repology.org/)):
<table>
<tbody>
<tr valign="top">
<td>
[![Packaging
status of quickemu](https://repology.org/badge/vertical-allrepos/quickemu.svg?header=quickemu)](https://repology.org/project/quickemu/versions)
</td>
<td>
[![Packaging
status](https://repology.org/badge/vertical-allrepos/quickgui.svg?header=quickgui)](https://repology.org/project/quickgui/versions)
</td>
</tr>
</tbody>
</table>
We have a Discord for this project:
[![Discord](https://img.shields.io/discord/712850672223125565?color=0C306A&label=WimpysWorld%20Discord&logo=Discord&logoColor=ffffff&style=flat-square)](https://discord.gg/sNmz3uw)
</div>
## Introduction
**Quickemu** is a wrapper for the excellent [QEMU](https://www.qemu.org/) that attempts to
automatically *"do the right thing"*, rather than expose exhaustive configuration options.
You decide what operating system you want to run, and Quickemu will figure out the best
way to do it for you.
The original objective of the project was to enable [quick testing of
Linux distributions](#linux-guests) where the virtual machine configurations can be
stored anywhere (such as external USB storage or your home directory)
and no elevated permissions are required to run the virtual machines.
**Quickemu now also includes comprehensive support for macOS and
Windows**.
**Quickemu now also includes comprehensive support for [macOS](#macos-guests)
and [Windows](#windows-guests)**.
See this (old) video where I explain some of my motivations for creating
Quickemu:
<div align="center">
[![Replace VirtualBox with Bash &
QEMU](https://img.youtube.com/vi/AOTYWEgw0hI/0.jpg)](https://www.youtube.com/watch?v=AOTYWEgw0hI)
</div>
## Features
@ -52,20 +96,70 @@ Windows**.
- EFI (with or without SecureBoot) and Legacy BIOS boot
- Graphical user interfaces available
Quickemu is a wrapper for the excellent [QEMU](https://www.qemu.org/)
that attempts to automatically *"do the right thing"*, rather than
expose exhaustive configuration options.
## Installation
We have a Discord for this project:
[![Discord](https://img.shields.io/discord/712850672223125565?color=0C306A&label=WimpysWorld%20Discord&logo=Discord&logoColor=ffffff&style=flat-square)](https://discord.gg/sNmz3uw)
### Arch Linux hosts
See this (old) video where I explain some of my motivations for creating
Quickemu.
Quickemu is available from the AUR (Arch user repository), and can be
installed via any AUR helper. Assuming your AUR helper is yay, Run the
following command:
[![Replace VirtualBox with Bash &
QEMU](https://img.youtube.com/vi/AOTYWEgw0hI/0.jpg)](https://www.youtube.com/watch?v=AOTYWEgw0hI)
``` bash
yay -Sy quickemu
```
## Requirements
### Ubuntu hosts
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
sudo apt-add-repository ppa:flexiondotorg/quickemu
sudo apt update
sudo apt install quickemu
```
### NixOS hosts
To quickly try quickemu:
```sh
nix-shell -p quickemu
```
To install via Nix profile:
```sh
nix-env -iA pkgs.quickemu
```
To install via NixOS config:
```nix
# /etc/nixos/configuration.nix
{pkgs, ...}: {
environment.systemPackages = with pkgs;
quickemu
};
}
```
To install via Flakes:
```sh
# TODO (flake users, please add an example!)
```
### Other Linux hosts (installing from source)
``` bash
git clone --filter=blob:none https://github.com/wimpysworld/quickemu
cd quickemu
```
When installing from source, you will need to install the following requirements manually:
- [QEMU](https://www.qemu.org/) (*6.0.0 or newer*) **with GTK, SDL,
SPICE & VirtFS support**
@ -91,9 +185,7 @@ QEMU](https://img.youtube.com/vi/AOTYWEgw0hI/0.jpg)](https://www.youtube.com/wat
- [zsync](http://zsync.moria.org.uk/)
- [unzip](http://www.info-zip.org/UnZip.html)
### Installing Requirements
For Ubuntu, Arch and nixos systems the
For Ubuntu, Arch and NixOS hosts, 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)
@ -101,110 +193,65 @@ 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
These examples may save a little typing:
Debian (and direct derivatives such as MX Linux):
#### Install requirements on Debian hosts
sudo apt install qemu bash coreutils ovmf grep jq lsb-base procps python3 genisoimage usbutils util-linux sed spice-client-gtk libtss2-tcti-swtpm0 wget xdg-user-dirs zsync unzip
This also applies to direct derivatives, such as MX Linux:
Fedora:
```sh
sudo apt install qemu bash coreutils ovmf grep jq lsb-base procps python3 genisoimage usbutils util-linux sed spice-client-gtk libtss2-tcti-swtpm0 wget xdg-user-dirs zsync unzip
```
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 socat
#### Install requirements on Fedora hosts
MacOS:
```sh
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
```
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)
#### Install requirements on macOS hosts
brew install qemu bash coreutils grep jq python@3.10 cdrtools gnu-sed spice-gtk wget zsync
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)
# Usage
```sh
brew install qemu bash coreutils grep jq python@3.10 cdrtools gnu-sed spice-gtk wget zsync
```
## Graphical User Interfaces
## GUI (quickgui)
While `quickemu` and `quickget` are designed for the terminal, a
graphical user interface is also available:
- **[Quickgui](https://github.com/quickgui/quickgui)** by [Mark
Johnson](https://github.com/marxjohnson) and [Yannick
Mauray](https://github.com/ymauray).
- **[Quickgui](https://github.com/quickgui/quickgui)** by [Mark Johnson](https://github.com/marxjohnson) and [Yannick Mauray](https://github.com/ymauray).
Many thanks to [Luke Wesley-Holley](https://github.com/Lukewh) and
[Philipp Kiemle](https://github.com/daPhipz) for creating the
**[Quickemu icons](https://github.com/Lukewh/quickemu-icons)** 🎨
To install Quickgui on Ubuntu:
### Quickgui for Ubuntu
``` bash
```sh
sudo add-apt-repository ppa:yannick-mauray/quickgui
sudo apt update
sudo apt install quickgui
```
### quickemu quickget X terminal project
Many thanks to [Luke Wesley-Holley](https://github.com/Lukewh) and
[Philipp Kiemle](https://github.com/daPhipz) for creating the
**[Quickemu icons](https://github.com/Lukewh/quickemu-icons)** 🎨
## TUI (qqx)
From Nov 2023, there is also a multi option desktop integrated text
interface, with lots of unique tools and utilities to help you make
interface, the **quickemu quickget X terminal project**, a.k.a. **qqX**,
with lots of unique tools and utilities to help you make
light work of installations, snapshots and disk management
- **[qqX](https://github.com/TuxVinyards/qqX)** is independently
curated by [Alex Genovese](https://github.com/TuxVinyards) (see the
github pages)
- **[qqX](https://github.com/TuxVinyards/qqX)** is independently curated
by [Alex Genovese](https://github.com/TuxVinyards) (see the github pages)
![qqX-vmm](https://github.com/TuxVinyards/qqX/assets/3956806/18e5c495-8072-49a5-8b9c-e1302549efcf)
# Install Quickemu
## Creating Linux guests 🐧
## Arch
Quickemu is available from the AUR (Arch user repository), and can be
installed via any AUR helper. Assuming your AUR helper is yay, Run the
following command:
``` bash
yay -Syu quickemu
```
## 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
sudo apt-add-repository ppa:flexiondotorg/quickemu
sudo apt update
sudo apt install quickemu
```
## Other Linux
``` bash
git clone --filter=blob:none https://github.com/wimpysworld/quickemu
cd quickemu
sudo make install
```
Now install all the **Requirements** documented above.
### Other sources
[Repology.org](https://repology.org/) found the following releases have
been packaged.
#### Quickemu
[![Packaging
status](https://repology.org/badge/vertical-allrepos/quickemu.svg)](https://repology.org/project/quickemu/versions)
#### Quickgui
[![Packaging
status](https://repology.org/badge/vertical-allrepos/quickgui.svg)](https://repology.org/project/quickgui/versions)
## Ubuntu Guest
### Ubuntu
`quickget` will automatically download an Ubuntu release and create the
virtual machine configuration.
@ -271,7 +318,7 @@ You can also use `quickget` with options to:
The `--show-iso-url`, `--test-iso-url`, and `--download-iso` options are fully
functional for all operating systems, including Windows and macOS.
## Other Operating Systems
### Other Operating Systems
`quickget` also supports:
@ -340,6 +387,8 @@ functional for all operating systems, including Windows and macOS.
- `xerolinux` (XeroLinux)
- `zorin` (Zorin OS)
### Custom Linux guests
Or you can download a Linux image and manually create a VM
configuration.
@ -365,7 +414,7 @@ quickemu --vm debian-bullseye.conf
- Install the SPICE WebDAV agent (`spice-webdavd`) in the guest to
enable file sharing.
## macOS Guest
## Creating macOS Guests 🍏
`quickget` automatically downloads a macOS recovery image and creates a
virtual machine configuration.
@ -512,16 +561,16 @@ sudo rm /Library/Preferences/SystemConfiguration/NetworkInterfaces.plist
Now reboot, and the App Store should work.
## Windows Guests
## Creating Windows guests 🪟
`quickget` can download
[Windows10](https://www.microsoft.com/software-download/windows10) and
[Windows 11](https://www.microsoft.com/software-download/windows11)
[**Windows 10**](https://www.microsoft.com/software-download/windows10) and
[**Windows 11**](https://www.microsoft.com/software-download/windows11)
automatically and create an optimised virtual machine configuration.
This configuration also includes the [VirtIO drivers for
Windows](https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/).
Windows 8.1 is also supported but doesn't feature any automated
**Windows 8.1** is also supported but doesn't feature any automated
installation or driver optimisation.
`quickget` can also download [Windows 10 LTSC](https://www.microsoft.com/en-us/evalcenter/download-windows-10-enterprise) and Windows Server [2012-r2](https://www.microsoft.com/en-us/evalcenter/download-windows-server-2012-r2), [2016](https://www.microsoft.com/en-us/evalcenter/download-windows-server-2016), [2019](https://www.microsoft.com/en-us/evalcenter/download-windows-server-2019), and [2022](https://www.microsoft.com/en-us/evalcenter/download-windows-server-2022). No automated installation is supported for these releases.
@ -564,7 +613,9 @@ secureboot="off"
- `tpm="on"` instructs `quickemu` to create a software emulated TPM
device using `swtpm`.
# SPICE
## Connecting to your VM
### SPICE
The following features are available while using the SPICE protocol:
@ -583,7 +634,7 @@ 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.
## Headless
### Headless
To start a VM with SPICE enabled, but no display attached use
`--display none`. This requires that the `spicy` client is installed,
@ -609,7 +660,7 @@ it from the host as follows:
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.
@ -618,7 +669,7 @@ real or fake device.
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
@ -626,7 +677,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
@ -641,7 +692,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
@ -653,14 +704,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
@ -668,12 +719,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
@ -694,15 +745,17 @@ 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 🐧 🪟
#### SPICE WebDAV 🐧 🪟
- TBD
## VirtIO-9P 🐧 🍏
#### VirtIO-9P 🐧 🍏
- TBD
# Network port forwarding
### Networking
#### Port forwarding
Add an additional line to your virtual machine configuration. For
example:
@ -714,14 +767,14 @@ 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.
# Disable networking
#### Disable networking
To completely disable all network interfaces in a guest VM add this
additional line to your virtual machine configuration:
- `network="none"`
# Restricted networking
#### Restricted networking
You can isolate the guest from the host (and broader network) using the
restrict option, which will restrict networking to just the guest and
@ -733,7 +786,7 @@ additional line to your virtual machine configuration:
- `network="restrict"`
# Bridged networking
#### Bridged networking
Connect your virtual machine to a preconfigured network bridge. Add an
additional line to your virtual machine configuration:
@ -749,19 +802,35 @@ So you can generate your own MAC addresses with:
- `macaddr="52:54:00:AB:51:AE"`
# 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
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**
##### Enabling SPICE redirection on NixOS
On NixOS, if you encounter this error:
```
Error setting facl: Operation not permitted
```
Try setting [the following option](https://search.nixos.org/options?channel=23.11&show=virtualisation.spiceUSBRedirection.enable&from=0&size=50&sort=relevance&type=packages&query=spiceusbredirec):
```nix
virtualisation.spiceUSBRedirection.enable = true;
```
#### 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
@ -788,14 +857,14 @@ 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
## Configuration
Here are the usage instructions:
@ -912,7 +981,7 @@ which will override system default screen sizes. The VM size will be
'pct' of the chosen screen. **If --fullscreen is chosen screen will be
fullsize instead of being scaled down by --screenpct value.**
# References
## References
Useful reference that assisted the development of Quickemu.