docs: add more nixos info (#171)

author: egasimus <adam@hack.bg>
2024-04-09 01:06:50 +02:00 · 2024-04-09 01:06:50 +02:00 · 51f17bb5ef
parent 68e23b41a7
commit 51f17bb5ef
1 changed files with 207 additions and 138 deletions
--- a/README.md
+++ b/README.md
@ -1,31 +1,75 @@
-<h1 align="center">
+<div align="center">
  <img src=".github/logo.png" alt="Quickemu" width="256" />
  <br />
  Quickemu
 </h1>
-<p align="center"><b>Quickly create and run optimised Windows, macOS and Linux desktop virtual machines.</b></p>
+<img src=".github/logo.png" alt="Quickemu" width="256" />
 <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
+# Quickemu
-Quickly create and run highly optimised desktop virtual machines for
+**Quickly create and run optimised Windows, macOS and Linux desktop virtual machines:**
 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
+</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
+<div align="center">
-Linux distributions where the virtual machine configurations can be
+
-stored anywhere, such as external USB storage or your home directory,
+<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
+**Quickemu now also includes comprehensive support for [macOS](#macos-guests)
-Windows**.
+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/)
+## Installation
 that attempts to automatically *"do the right thing"*, rather than
 expose exhaustive configuration options.
-We have a Discord for this project:
+### Arch Linux hosts
 [![Discord](https://img.shields.io/discord/712850672223125565?color=0C306A&label=WimpysWorld%20Discord&logo=Discord&logoColor=ffffff&style=flat-square)](https://discord.gg/sNmz3uw)
-See this (old) video where I explain some of my motivations for creating
+Quickemu is available from the AUR (Arch user repository), and can be
-Quickemu.
+installed via any AUR helper. Assuming your AUR helper is yay, Run the
 following command:
-[![Replace VirtualBox with Bash &
+``` bash
-QEMU](https://img.youtube.com/vi/AOTYWEgw0hI/0.jpg)](https://www.youtube.com/watch?v=AOTYWEgw0hI)
+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 hosts, the
 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)
@ -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
+#### Install requirements on macOS hosts
 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
+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
+- **[Quickgui](https://github.com/quickgui/quickgui)** by [Mark Johnson](https://github.com/marxjohnson) and [Yannick Mauray](https://github.com/ymauray).
    Johnson](https://github.com/marxjohnson) and [Yannick
    Mauray](https://github.com/ymauray).
-Many thanks to [Luke Wesley-Holley](https://github.com/Lukewh) and
+To install Quickgui on Ubuntu:
 [Philipp Kiemle](https://github.com/daPhipz) for creating the
 **[Quickemu icons](https://github.com/Lukewh/quickemu-icons)** 🎨
-### Quickgui for Ubuntu
+```sh
 ``` bash
 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
+-   **[qqX](https://github.com/TuxVinyards/qqX)** is independently curated
-    curated by [Alex Genovese](https://github.com/TuxVinyards) (see the
+    by [Alex Genovese](https://github.com/TuxVinyards) (see the github pages)
    github pages)
 ![qqX-vmm](https://github.com/TuxVinyards/qqX/assets/3956806/18e5c495-8072-49a5-8b9c-e1302549efcf)
-# Install Quickemu
+## Creating Linux guests 🐧
-## Arch
+### Ubuntu
 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
 `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 10**](https://www.microsoft.com/software-download/windows10) and
-[Windows 11](https://www.microsoft.com/software-download/windows11)
+[**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
+elevated permission:
-select `Input` -\> `Select USB Device for redirection` from the menu to
+
 * 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.