diff --git a/docs/quickemu.1 b/docs/quickemu.1 index 1e1ab6e..31bc283 100644 --- a/docs/quickemu.1 +++ b/docs/quickemu.1 @@ -1,6 +1,6 @@ .\" Automatically generated by Pandoc 3.1.13 .\" -.TH "QUICKEMU" "1" "April 30, 2024" "quickemu" "Quickemu User Manual" +.TH "QUICKEMU" "1" "May 4, 2024" "quickemu" "Quickemu User Manual" .SH NAME quickemu \- A quick VM builder and manager .SH SYNOPSIS @@ -142,7 +142,7 @@ Print version .TP \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 +.SH Introduction \f[B]Quickemu\f[R] is a wrapper for the excellent \c .UR https://www.qemu.org/ QEMU @@ -152,14 +152,25 @@ 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. .PP -The original objective of the project was to enable quick testing of -Linux distributions where the virtual machine configurations can be -stored anywhere (such as external USB storage or your home directory) -and no elevated permissions are required to run the virtual machines. +The original objective of the project was to \c +.UR https://github.com/quickemu-project/quickemu/wiki/02-Create-Linux-virtual-machines +enable quick testing of Linux distributions +.UE \c +\ 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. .PP -\f[B]Quickemu now also includes comprehensive support for macOS and -Windows\f[R]. -.SS Features +\f[B]Today, Quickemu includes comprehensive support for \c +.UR https://github.com/quickemu-project/quickemu/wiki/03-Create-macOS-virtual-machines +macOS +.UE \c +, \c +.UR https://github.com/quickemu-project/quickemu/wiki/04-Create-Windows-virtual-machines +Windows +.UE \c +\f[R], most of the BSDs, novel non\-Linux operating systems such as +FreeDOS, Haiku, KolibriOS, OpenIndiana, ReactOS, and more. +.SH Features .IP \[bu] 2 \f[B]macOS\f[R] Sonoma, Ventura, Monterey, Big Sur, Catalina, Mojave & High Sierra @@ -176,7 +187,7 @@ official Ubuntu flavours .UE \c \f[R] .IP \[bu] 2 -\f[B]Over 360 operating system editions are supported!\f[R] +\f[B]Nearly 1000 operating system editions are supported!\f[R] .IP \[bu] 2 Full SPICE support including host/guest clipboard sharing .IP \[bu] 2 @@ -308,11 +319,6 @@ swtpm .UE \c .IP \[bu] 2 \c -.UR https://www.gnu.org/software/wget/ -Wget -.UE \c -.IP \[bu] 2 -\c .UR https://www.freedesktop.org/wiki/Software/xdg-user-dirs/ xdg\-user\-dirs .UE \c @@ -353,12 +359,12 @@ These examples may save a little typing: This also applies to derivatives: .IP .EX -sudo apt install qemu bash coreutils curl ovmf grep jq lsb\-base procps python3 genisoimage usbutils util\-linux sed socat spice\-client\-gtk libtss2\-tcti\-swtpm0 wget xdg\-user\-dirs zsync unzip +sudo apt install qemu bash coreutils curl ovmf grep jq lsb\-base procps python3 genisoimage usbutils util\-linux sed socat spice\-client\-gtk libtss2\-tcti\-swtpm0 xdg\-user\-dirs zsync unzip .EE .SS Install requirements on Fedora hosts .IP .EX -sudo dnf install qemu bash coreutils curl edk2\-tools grep jq lsb procps python3 genisoimage usbutils util\-linux sed socat spice\-gtk\-tools swtpm wget xdg\-user\-dirs xrandr unzip +sudo dnf install qemu bash coreutils curl edk2\-tools grep jq lsb procps python3 genisoimage usbutils util\-linux sed socat spice\-gtk\-tools swtpm xdg\-user\-dirs xrandr unzip .EE .SS Install requirements on macOS hosts This is a \f[B]work in progress\f[R] (see \c @@ -368,7 +374,7 @@ issue 248 \ for other steps and changes that may enable running on MacOS) .IP .EX -brew install qemu bash coreutils curl grep jq python\[at]3.10 cdrtools gnu\-sed spice\-gtk wget zsync +brew install qemu bash coreutils curl grep jq python\[at]3.10 cdrtools gnu\-sed spice\-gtk zsync .EE .SS \c .UR https://github.com/quickemu-project/quickemu/wiki/07-Alternative-frontends @@ -512,19 +518,17 @@ wiki You can also use \f[CR]quickget\f[R] with advanced options : .IP .EX - \-[12345] : Show info* about OS - \-\-download (\-d) [ed] : Download the ISO only; no VM configuration - \-\-create\-config (\-cc) [path/url]: Create default VM config for image - \-\-open\-homepage (\-o) : Open homepage for the OS - \-\-version (\-v) : Show version - \-\-help (\-h) : Show this help message - \-\-url (\-u) [ed] : Show download URL for an OS release/edition - \-\-url\-all (\-ua) : Show all download URLs for an OS - \-\-check (\-c) [re] [ed] : Check download an OS release/edition is available - \-\-check\-all (\-ca) : Check all downloads for an OS are available - \-\-list (\-l) : List all supported systems in plain text - \-\-list\-csv (\-lc) : List all supported systems in csv format - \-\-list\-json (\-lj) : List all supported systems in json format + \-[12345] : Show info* about OS + \-\-download (\-d) [ed] : Download image; no VM configuration + \-\-create\-config (\-cc) [path/url]: Create default VM config for image + \-\-open\-homepage (\-o) : Open homepage for the OS + \-\-version (\-v) : Show version + \-\-help (\-h) : Show this help message + \-\-url (\-u) [os] [re] [ed] : Show image URL(s) + \-\-check (\-c) [os] [re] [ed] : Check image URL(s) + \-\-list (\-l) : List all supported systems + \-\-list\-csv (\-lc) : List everything in csv format + \-\-list\-json (\-lj) : List everything in json format .EE .PP Here are some typical uses @@ -651,6 +655,8 @@ wiki .IP \[bu] 2 \f[CR]nixos\f[R] (NixOS) .IP \[bu] 2 +\f[CR]nwg\-shell\f[R] (nwg\-shell) +.IP \[bu] 2 \f[CR]openbsd\f[R] (OpenBSD) .IP \[bu] 2 \f[CR]openindiana\f[R] (OpenIndiana) @@ -876,115 +882,13 @@ Sur and newer, but not previous releases. And VirtIO Block Media (disks) are supported/stable in Catalina and newer. .RE -.SS macOS compatibility -There are some considerations when running macOS via Quickemu. -.IP \[bu] 2 -Supported macOS releases: -.RS 2 -.IP \[bu] 2 -High Sierra -.IP \[bu] 2 -Mojave -.IP \[bu] 2 -Catalina \f[B](Recommended)\f[R] -.IP \[bu] 2 -Big Sur -.IP \[bu] 2 -Monterey -.IP \[bu] 2 -Ventura -.IP \[bu] 2 -Sonoma -.RE -.IP \[bu] 2 -\f[CR]quickemu\f[R] will automatically download the required \c -.UR https://github.com/acidanthera/OpenCorePkg -OpenCore -.UE \c -\ bootloader and OVMF firmware from \c -.UR https://github.com/kholia/OSX-KVM -OSX\-KVM +.PP +There is further advice and information about macOS guests in the +project \c +.UR https://github.com/quickemu-project/quickemu/wiki/03-Create-macOS-virtual-machines#automatically-create-macos-guests +wiki .UE \c \&. -.IP \[bu] 2 -Optimised by default, but no GPU acceleration is available. -.RS 2 -.IP \[bu] 2 -Host CPU vendor is detected and guest CPU is optimised accordingly. -.IP \[bu] 2 -\c -.UR https://www.kraxel.org/blog/2019/06/macos-qemu-guest/ -VirtIO Block Media -.UE \c -\ is used for the system disk where supported. -.IP \[bu] 2 -\c -.UR http://philjordan.eu/osx-virt/ -VirtIO \f[CR]usb\-tablet\f[R] -.UE \c -\ is used for the mouse. -.IP \[bu] 2 -VirtIO Network (\f[CR]virtio\-net\f[R]) is supported and enabled on -macOS Big Sur and newer but previous releases use \f[CR]vmxnet3\f[R]. -.IP \[bu] 2 -VirtIO Memory Ballooning is supported and enabled on macOS Big Sur and -newer but disabled for other support macOS releases. -.RE -.IP \[bu] 2 -USB host and SPICE pass\-through is: -.RS 2 -.IP \[bu] 2 -UHCI (USB 2.0) on macOS Catalina and earlier. -.IP \[bu] 2 -XHCI (USB 3.0) on macOS Big Sur and newer. -.RE -.IP \[bu] 2 -Display resolution can only be changed via macOS System Preferences. -.IP \[bu] 2 -\f[B]Full Duplex audio requires \c -.UR https://github.com/chris1111/VoodooHDA-OC -VoodooHDA OC -.UE \c -\ or pass\-through a USB audio\-device to the macOS guest VM\f[R]. -.IP \[bu] 2 -NOTE! -\c -.UR https://disable-gatekeeper.github.io/ -Gatekeeper -.UE \c -\ and \c -.UR https://developer.apple.com/documentation/security/disabling_and_enabling_system_integrity_protection -System Integrity Protection (SIP) -.UE \c -\ need to be disabled to install VoodooHDA OC -.IP \[bu] 2 -File sharing between guest and host is available via \c -.UR https://wiki.qemu.org/Documentation/9psetup -virtio\-9p -.UE \c -\ and \c -.UR https://gitlab.gnome.org/GNOME/phodav/-/merge_requests/24 -SPICE webdavd -.UE \c -\&. -.IP \[bu] 2 -Copy/paste via SPICE agent is \f[B]not available on macOS\f[R]. -.SS macOS App Store -If you see \f[I]\[lq]Your device or computer could not be -verified\[rq]\f[R] when you try to login to the App Store, make sure -that your wired ethernet device is \f[CR]en0\f[R]. -Use \f[CR]ifconfig\f[R] in a terminal to verify this. -.PP -If the wired ethernet device is not \f[CR]en0\f[R], then then go to -\f[I]System Preferences\f[R] \-> \f[I]Network\f[R], delete all the -network devices and apply the changes. -Next, open a terminal and run the following: -.IP -.EX -sudo rm /Library/Preferences/SystemConfiguration/NetworkInterfaces.plist -.EE -.PP -Now reboot, and the App Store should work. .SS \c .UR https://github.com/quickemu-project/quickemu/wiki/04-Create-Windows-virtual-machines Creating Windows guests @@ -1048,44 +952,19 @@ Username: \f[CR]Quickemu\f[R] .IP \[bu] 2 Password: \f[CR]quickemu\f[R] .RE -.SS Regional versions -By default \f[CR]quickget\f[R] will download the \f[I]\[lq]English -International\[rq]\f[R] release (\f[I]\[lq]English (United -States)\[rq]\f[R] for server releases), but you can optionally specify -one of the supported languages: For example: -.IP -.EX -quickget windows 11 \[dq]Chinese (Traditional)\[dq] -.EE .PP -The default Windows 11 configuration looks like this: -.IP -.EX -guest_os=\[dq]windows\[dq] -disk_img=\[dq]windows\-11/disk.qcow2\[dq] -iso=\[dq]windows\-11/windows\-11.iso\[dq] -fixed_iso=\[dq]windows\-11/virtio\-win.iso\[dq] -tpm=\[dq]on\[dq] -secureboot=\[dq]off\[dq] -.EE -.IP \[bu] 2 -\f[CR]guest_os=\[dq]windows\[dq]\f[R] instructs \f[CR]quickemu\f[R] to -optimise for Windows. -.IP \[bu] 2 -\f[CR]fixed_iso=\f[R] specifies the ISO image that provides VirtIO -drivers. -.IP \[bu] 2 -\f[CR]tpm=\[dq]on\[dq]\f[R] instructs \f[CR]quickemu\f[R] to create a -software emulated TPM device using \f[CR]swtpm\f[R]. +Further information is available from the project \c +.UR https://github.com/quickemu-project/quickemu/wiki/04-Create-Windows-virtual-machines +wiki +.UE \c .SS Configuration Here are the usage instructions: .IP .EX - Usage - quickemu \-\-vm ubuntu.conf [optional params] + quickemu \-\-vm ubuntu.conf -List of optional parameters: +Arguments \-\-access : Enable remote spice access support. \[aq]local\[aq] (default), \[aq]remote\[aq], \[aq]clientipaddress\[aq] \-\-braille : Enable braille support. Requires SDL. \-\-delete\-disk : Delete the disk image and EFI variables diff --git a/docs/quickemu.1.md b/docs/quickemu.1.md index 7f1d4cb..2d67fa2 100644 --- a/docs/quickemu.1.md +++ b/docs/quickemu.1.md @@ -1,6 +1,6 @@ --- author: Martin Wimpress -date: April 30, 2024 +date: May 4, 2024 footer: quickemu header: Quickemu User Manual section: 1 @@ -144,7 +144,7 @@ You can also pass optional parameters **quickemu --vm ubuntu-mate-22.04.conf** : Launches the VM specified in the file *ubuntu-mate-22.04.conf* -## Introduction +# Introduction **Quickemu** is a wrapper for the excellent [QEMU](https://www.qemu.org/) that attempts to automatically *"do the @@ -152,24 +152,27 @@ 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](#creating-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. +The original objective of the project was to [enable quick testing of +Linux +distributions](https://github.com/quickemu-project/quickemu/wiki/02-Create-Linux-virtual-machines) +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](#creating-macos-guests-) and -[Windows](#creating-windows-guests-)**. +**Today, Quickemu includes comprehensive support for +[macOS](https://github.com/quickemu-project/quickemu/wiki/03-Create-macOS-virtual-machines), +[Windows](https://github.com/quickemu-project/quickemu/wiki/04-Create-Windows-virtual-machines)**, +most of the BSDs, novel non-Linux operating systems such as FreeDOS, +Haiku, KolibriOS, OpenIndiana, ReactOS, and more. -## Features +# Features - **macOS** Sonoma, Ventura, Monterey, Big Sur, Catalina, Mojave & High Sierra - **Windows** 10 and 11 including TPM 2.0 - [Ubuntu](https://ubuntu.com/desktop) and all the **[official Ubuntu flavours](https://ubuntu.com/download/flavours)** -- **Over 360 operating system editions are supported!** +- **Nearly 1000 operating system editions are supported!** - Full SPICE support including host/guest clipboard sharing - VirtIO-webdavd file sharing for Linux and Windows guests - VirtIO-9p file sharing for Linux and macOS guests @@ -345,19 +348,17 @@ may have further information. You can also use `quickget` with advanced options : ``` text - -[12345] : Show info* about OS - --download (-d) [ed] : Download the ISO only; no VM configuration - --create-config (-cc) [path/url]: Create default VM config for image - --open-homepage (-o) : Open homepage for the OS - --version (-v) : Show version - --help (-h) : Show this help message - --url (-u) [ed] : Show download URL for an OS release/edition - --url-all (-ua) : Show all download URLs for an OS - --check (-c) [re] [ed] : Check download an OS release/edition is available - --check-all (-ca) : Check all downloads for an OS are available - --list (-l) : List all supported systems in plain text - --list-csv (-lc) : List all supported systems in csv format - --list-json (-lj) : List all supported systems in json format + -[12345] : Show info* about OS + --download (-d) [ed] : Download image; no VM configuration + --create-config (-cc) [path/url]: Create default VM config for image + --open-homepage (-o) : Open homepage for the OS + --version (-v) : Show version + --help (-h) : Show this help message + --url (-u) [os] [re] [ed] : Show image URL(s) + --check (-c) [os] [re] [ed] : Check image URL(s) + --list (-l) : List all supported systems + --list-csv (-lc) : List everything in csv format + --list-json (-lj) : List everything in json format ``` Here are some typical uses @@ -433,6 +434,7 @@ Further information is available from the project - `netbsd` (NetBSD) - `nitrux` (Nitrux) - `nixos` (NixOS) +- `nwg-shell` (nwg-shell) - `openbsd` (OpenBSD) - `openindiana` (OpenIndiana) - `opensuse` (openSUSE) @@ -587,64 +589,9 @@ macos_release="catalina" - And VirtIO Block Media (disks) are supported/stable in Catalina and newer. -### macOS compatibility - -There are some considerations when running macOS via Quickemu. - -- Supported macOS releases: - - High Sierra - - Mojave - - Catalina **(Recommended)** - - Big Sur - - Monterey - - Ventura - - Sonoma -- `quickemu` will automatically download the required - [OpenCore](https://github.com/acidanthera/OpenCorePkg) bootloader - and OVMF firmware from [OSX-KVM](https://github.com/kholia/OSX-KVM). -- Optimised by default, but no GPU acceleration is available. - - Host CPU vendor is detected and guest CPU is optimised - accordingly. - - [VirtIO Block - Media](https://www.kraxel.org/blog/2019/06/macos-qemu-guest/) is - used for the system disk where supported. - - [VirtIO `usb-tablet`](http://philjordan.eu/osx-virt/) is used - for the mouse. - - VirtIO Network (`virtio-net`) is supported and enabled on macOS - Big Sur and newer but previous releases use `vmxnet3`. - - VirtIO Memory Ballooning is supported and enabled on macOS Big - Sur and newer but disabled for other support macOS releases. -- USB host and SPICE pass-through is: - - UHCI (USB 2.0) on macOS Catalina and earlier. - - XHCI (USB 3.0) on macOS Big Sur and newer. -- Display resolution can only be changed via macOS System Preferences. -- **Full Duplex audio requires [VoodooHDA - OC](https://github.com/chris1111/VoodooHDA-OC) or pass-through a USB - audio-device to the macOS guest VM**. -- NOTE! [Gatekeeper](https://disable-gatekeeper.github.io/) and - [System Integrity Protection - (SIP)](https://developer.apple.com/documentation/security/disabling_and_enabling_system_integrity_protection) - need to be disabled to install VoodooHDA OC -- File sharing between guest and host is available via - [virtio-9p](https://wiki.qemu.org/Documentation/9psetup) and [SPICE - webdavd](https://gitlab.gnome.org/GNOME/phodav/-/merge_requests/24). -- Copy/paste via SPICE agent is **not available on macOS**. - -### macOS App Store - -If you see *"Your device or computer could not be verified"* when you -try to login to the App Store, make sure that your wired ethernet device -is `en0`. Use `ifconfig` in a terminal to verify this. - -If the wired ethernet device is not `en0`, then then go to *System -Preferences* -\> *Network*, delete all the network devices and apply the -changes. Next, open a terminal and run the following: - -``` shell -sudo rm /Library/Preferences/SystemConfiguration/NetworkInterfaces.plist -``` - -Now reboot, and the App Store should work. +There is further advice and information about macOS guests in the +project +[wiki](https://github.com/quickemu-project/quickemu/wiki/03-Create-macOS-virtual-machines#automatically-create-macos-guests). ## [Creating Windows guests](https://github.com/quickemu-project/quickemu/wiki/04-Create-Windows-virtual-machines) 🪟 @@ -680,42 +627,18 @@ quickemu --vm windows-11.conf - Username: `Quickemu` - Password: `quickemu` -### Regional versions - -By default `quickget` will download the *"English International"* -release (*"English (United States)"* for server releases), but you can -optionally specify one of the supported languages: For example: - -``` shell -quickget windows 11 "Chinese (Traditional)" -``` - -The default Windows 11 configuration looks like this: - -``` shell -guest_os="windows" -disk_img="windows-11/disk.qcow2" -iso="windows-11/windows-11.iso" -fixed_iso="windows-11/virtio-win.iso" -tpm="on" -secureboot="off" -``` - -- `guest_os="windows"` instructs `quickemu` to optimise for Windows. -- `fixed_iso=` specifies the ISO image that provides VirtIO drivers. -- `tpm="on"` instructs `quickemu` to create a software emulated TPM - device using `swtpm`. +Further information is available from the project +[wiki](https://github.com/quickemu-project/quickemu/wiki/04-Create-Windows-virtual-machines) ## Configuration Here are the usage instructions: ``` text - Usage - quickemu --vm ubuntu.conf [optional params] + quickemu --vm ubuntu.conf -List of optional parameters: +Arguments --access : Enable remote spice access support. 'local' (default), 'remote', 'clientipaddress' --braille : Enable braille support. Requires SDL. --delete-disk : Delete the disk image and EFI variables diff --git a/docs/quickemu_conf.1 b/docs/quickemu_conf.1 index 8095fc6..e63bebf 100644 --- a/docs/quickemu_conf.1 +++ b/docs/quickemu_conf.1 @@ -1,6 +1,6 @@ .\" Automatically generated by Pandoc 3.1.13 .\" -.TH "QUICKEMU_CONF" "1" "April 30, 2024" "quickemu_conf" "Quickemu Configuration Manual" +.TH "QUICKEMU_CONF" "1" "May 4, 2024" "quickemu_conf" "Quickemu Configuration Manual" .SH NAME quickemu_conf \- Options and parameters in the quickemu .conf .SH DESCRIPTION diff --git a/docs/quickemu_conf.1.md b/docs/quickemu_conf.1.md index d64dece..ca95a4c 100644 --- a/docs/quickemu_conf.1.md +++ b/docs/quickemu_conf.1.md @@ -1,6 +1,6 @@ --- author: Martin Wimpress -date: April 30, 2024 +date: May 4, 2024 footer: quickemu_conf header: Quickemu Configuration Manual section: 1 diff --git a/docs/quickget.1 b/docs/quickget.1 index 149853d..fdb7745 100644 --- a/docs/quickget.1 +++ b/docs/quickget.1 @@ -1,6 +1,6 @@ .\" Automatically generated by Pandoc 3.1.13 .\" -.TH "QUICKGET" "1" "April 30, 2024" "quickget" "Quickget User Manual" +.TH "QUICKGET" "1" "May 4, 2024" "quickget" "Quickget User Manual" .SH NAME quickget \- download and prepare materials for building a quickemu VM .SH SYNOPSIS @@ -110,19 +110,17 @@ wiki You can also use \f[CR]quickget\f[R] with advanced options : .IP .EX - \-[12345] : Show info* about OS - \-\-download (\-d) [ed] : Download the ISO only; no VM configuration - \-\-create\-config (\-cc) [path/url]: Create default VM config for image - \-\-open\-homepage (\-o) : Open homepage for the OS - \-\-version (\-v) : Show version - \-\-help (\-h) : Show this help message - \-\-url (\-u) [ed] : Show download URL for an OS release/edition - \-\-url\-all (\-ua) : Show all download URLs for an OS - \-\-check (\-c) [re] [ed] : Check download an OS release/edition is available - \-\-check\-all (\-ca) : Check all downloads for an OS are available - \-\-list (\-l) : List all supported systems in plain text - \-\-list\-csv (\-lc) : List all supported systems in csv format - \-\-list\-json (\-lj) : List all supported systems in json format + \-[12345] : Show info* about OS + \-\-download (\-d) [ed] : Download image; no VM configuration + \-\-create\-config (\-cc) [path/url]: Create default VM config for image + \-\-open\-homepage (\-o) : Open homepage for the OS + \-\-version (\-v) : Show version + \-\-help (\-h) : Show this help message + \-\-url (\-u) [os] [re] [ed] : Show image URL(s) + \-\-check (\-c) [os] [re] [ed] : Check image URL(s) + \-\-list (\-l) : List all supported systems + \-\-list\-csv (\-lc) : List everything in csv format + \-\-list\-json (\-lj) : List everything in json format .EE .PP Here are some typical uses @@ -249,6 +247,8 @@ wiki .IP \[bu] 2 \f[CR]nixos\f[R] (NixOS) .IP \[bu] 2 +\f[CR]nwg\-shell\f[R] (nwg\-shell) +.IP \[bu] 2 \f[CR]openbsd\f[R] (OpenBSD) .IP \[bu] 2 \f[CR]openindiana\f[R] (OpenIndiana) @@ -474,115 +474,13 @@ Sur and newer, but not previous releases. And VirtIO Block Media (disks) are supported/stable in Catalina and newer. .RE -.SS macOS compatibility -There are some considerations when running macOS via Quickemu. -.IP \[bu] 2 -Supported macOS releases: -.RS 2 -.IP \[bu] 2 -High Sierra -.IP \[bu] 2 -Mojave -.IP \[bu] 2 -Catalina \f[B](Recommended)\f[R] -.IP \[bu] 2 -Big Sur -.IP \[bu] 2 -Monterey -.IP \[bu] 2 -Ventura -.IP \[bu] 2 -Sonoma -.RE -.IP \[bu] 2 -\f[CR]quickemu\f[R] will automatically download the required \c -.UR https://github.com/acidanthera/OpenCorePkg -OpenCore -.UE \c -\ bootloader and OVMF firmware from \c -.UR https://github.com/kholia/OSX-KVM -OSX\-KVM +.PP +There is further advice and information about macOS guests in the +project \c +.UR https://github.com/quickemu-project/quickemu/wiki/03-Create-macOS-virtual-machines#automatically-create-macos-guests +wiki .UE \c \&. -.IP \[bu] 2 -Optimised by default, but no GPU acceleration is available. -.RS 2 -.IP \[bu] 2 -Host CPU vendor is detected and guest CPU is optimised accordingly. -.IP \[bu] 2 -\c -.UR https://www.kraxel.org/blog/2019/06/macos-qemu-guest/ -VirtIO Block Media -.UE \c -\ is used for the system disk where supported. -.IP \[bu] 2 -\c -.UR http://philjordan.eu/osx-virt/ -VirtIO \f[CR]usb\-tablet\f[R] -.UE \c -\ is used for the mouse. -.IP \[bu] 2 -VirtIO Network (\f[CR]virtio\-net\f[R]) is supported and enabled on -macOS Big Sur and newer but previous releases use \f[CR]vmxnet3\f[R]. -.IP \[bu] 2 -VirtIO Memory Ballooning is supported and enabled on macOS Big Sur and -newer but disabled for other support macOS releases. -.RE -.IP \[bu] 2 -USB host and SPICE pass\-through is: -.RS 2 -.IP \[bu] 2 -UHCI (USB 2.0) on macOS Catalina and earlier. -.IP \[bu] 2 -XHCI (USB 3.0) on macOS Big Sur and newer. -.RE -.IP \[bu] 2 -Display resolution can only be changed via macOS System Preferences. -.IP \[bu] 2 -\f[B]Full Duplex audio requires \c -.UR https://github.com/chris1111/VoodooHDA-OC -VoodooHDA OC -.UE \c -\ or pass\-through a USB audio\-device to the macOS guest VM\f[R]. -.IP \[bu] 2 -NOTE! -\c -.UR https://disable-gatekeeper.github.io/ -Gatekeeper -.UE \c -\ and \c -.UR https://developer.apple.com/documentation/security/disabling_and_enabling_system_integrity_protection -System Integrity Protection (SIP) -.UE \c -\ need to be disabled to install VoodooHDA OC -.IP \[bu] 2 -File sharing between guest and host is available via \c -.UR https://wiki.qemu.org/Documentation/9psetup -virtio\-9p -.UE \c -\ and \c -.UR https://gitlab.gnome.org/GNOME/phodav/-/merge_requests/24 -SPICE webdavd -.UE \c -\&. -.IP \[bu] 2 -Copy/paste via SPICE agent is \f[B]not available on macOS\f[R]. -.SS macOS App Store -If you see \f[I]\[lq]Your device or computer could not be -verified\[rq]\f[R] when you try to login to the App Store, make sure -that your wired ethernet device is \f[CR]en0\f[R]. -Use \f[CR]ifconfig\f[R] in a terminal to verify this. -.PP -If the wired ethernet device is not \f[CR]en0\f[R], then then go to -\f[I]System Preferences\f[R] \-> \f[I]Network\f[R], delete all the -network devices and apply the changes. -Next, open a terminal and run the following: -.IP -.EX -sudo rm /Library/Preferences/SystemConfiguration/NetworkInterfaces.plist -.EE -.PP -Now reboot, and the App Store should work. .SS \c .UR https://github.com/quickemu-project/quickemu/wiki/04-Create-Windows-virtual-machines Creating Windows guests @@ -646,35 +544,11 @@ Username: \f[CR]Quickemu\f[R] .IP \[bu] 2 Password: \f[CR]quickemu\f[R] .RE -.SS Regional versions -By default \f[CR]quickget\f[R] will download the \f[I]\[lq]English -International\[rq]\f[R] release (\f[I]\[lq]English (United -States)\[rq]\f[R] for server releases), but you can optionally specify -one of the supported languages: For example: -.IP -.EX -quickget windows 11 \[dq]Chinese (Traditional)\[dq] -.EE .PP -The default Windows 11 configuration looks like this: -.IP -.EX -guest_os=\[dq]windows\[dq] -disk_img=\[dq]windows\-11/disk.qcow2\[dq] -iso=\[dq]windows\-11/windows\-11.iso\[dq] -fixed_iso=\[dq]windows\-11/virtio\-win.iso\[dq] -tpm=\[dq]on\[dq] -secureboot=\[dq]off\[dq] -.EE -.IP \[bu] 2 -\f[CR]guest_os=\[dq]windows\[dq]\f[R] instructs \f[CR]quickemu\f[R] to -optimise for Windows. -.IP \[bu] 2 -\f[CR]fixed_iso=\f[R] specifies the ISO image that provides VirtIO -drivers. -.IP \[bu] 2 -\f[CR]tpm=\[dq]on\[dq]\f[R] instructs \f[CR]quickemu\f[R] to create a -software emulated TPM device using \f[CR]swtpm\f[R]. +Further information is available from the project \c +.UR https://github.com/quickemu-project/quickemu/wiki/04-Create-Windows-virtual-machines +wiki +.UE \c .SH AUTHORS Written by Martin Wimpress. .SH BUGS diff --git a/docs/quickget.1.md b/docs/quickget.1.md index 5ba411b..a9ee1c9 100644 --- a/docs/quickget.1.md +++ b/docs/quickget.1.md @@ -1,6 +1,6 @@ --- author: Martin Wimpress -date: April 30, 2024 +date: May 4, 2024 footer: quickget header: Quickget User Manual section: 1 @@ -106,19 +106,17 @@ may have further information. You can also use `quickget` with advanced options : ``` text - -[12345] : Show info* about OS - --download (-d) [ed] : Download the ISO only; no VM configuration - --create-config (-cc) [path/url]: Create default VM config for image - --open-homepage (-o) : Open homepage for the OS - --version (-v) : Show version - --help (-h) : Show this help message - --url (-u) [ed] : Show download URL for an OS release/edition - --url-all (-ua) : Show all download URLs for an OS - --check (-c) [re] [ed] : Check download an OS release/edition is available - --check-all (-ca) : Check all downloads for an OS are available - --list (-l) : List all supported systems in plain text - --list-csv (-lc) : List all supported systems in csv format - --list-json (-lj) : List all supported systems in json format + -[12345] : Show info* about OS + --download (-d) [ed] : Download image; no VM configuration + --create-config (-cc) [path/url]: Create default VM config for image + --open-homepage (-o) : Open homepage for the OS + --version (-v) : Show version + --help (-h) : Show this help message + --url (-u) [os] [re] [ed] : Show image URL(s) + --check (-c) [os] [re] [ed] : Check image URL(s) + --list (-l) : List all supported systems + --list-csv (-lc) : List everything in csv format + --list-json (-lj) : List everything in json format ``` Here are some typical uses @@ -194,6 +192,7 @@ Further information is available from the project - `netbsd` (NetBSD) - `nitrux` (Nitrux) - `nixos` (NixOS) +- `nwg-shell` (nwg-shell) - `openbsd` (OpenBSD) - `openindiana` (OpenIndiana) - `opensuse` (openSUSE) @@ -348,64 +347,9 @@ macos_release="catalina" - And VirtIO Block Media (disks) are supported/stable in Catalina and newer. -### macOS compatibility - -There are some considerations when running macOS via Quickemu. - -- Supported macOS releases: - - High Sierra - - Mojave - - Catalina **(Recommended)** - - Big Sur - - Monterey - - Ventura - - Sonoma -- `quickemu` will automatically download the required - [OpenCore](https://github.com/acidanthera/OpenCorePkg) bootloader - and OVMF firmware from [OSX-KVM](https://github.com/kholia/OSX-KVM). -- Optimised by default, but no GPU acceleration is available. - - Host CPU vendor is detected and guest CPU is optimised - accordingly. - - [VirtIO Block - Media](https://www.kraxel.org/blog/2019/06/macos-qemu-guest/) is - used for the system disk where supported. - - [VirtIO `usb-tablet`](http://philjordan.eu/osx-virt/) is used - for the mouse. - - VirtIO Network (`virtio-net`) is supported and enabled on macOS - Big Sur and newer but previous releases use `vmxnet3`. - - VirtIO Memory Ballooning is supported and enabled on macOS Big - Sur and newer but disabled for other support macOS releases. -- USB host and SPICE pass-through is: - - UHCI (USB 2.0) on macOS Catalina and earlier. - - XHCI (USB 3.0) on macOS Big Sur and newer. -- Display resolution can only be changed via macOS System Preferences. -- **Full Duplex audio requires [VoodooHDA - OC](https://github.com/chris1111/VoodooHDA-OC) or pass-through a USB - audio-device to the macOS guest VM**. -- NOTE! [Gatekeeper](https://disable-gatekeeper.github.io/) and - [System Integrity Protection - (SIP)](https://developer.apple.com/documentation/security/disabling_and_enabling_system_integrity_protection) - need to be disabled to install VoodooHDA OC -- File sharing between guest and host is available via - [virtio-9p](https://wiki.qemu.org/Documentation/9psetup) and [SPICE - webdavd](https://gitlab.gnome.org/GNOME/phodav/-/merge_requests/24). -- Copy/paste via SPICE agent is **not available on macOS**. - -### macOS App Store - -If you see *"Your device or computer could not be verified"* when you -try to login to the App Store, make sure that your wired ethernet device -is `en0`. Use `ifconfig` in a terminal to verify this. - -If the wired ethernet device is not `en0`, then then go to *System -Preferences* -\> *Network*, delete all the network devices and apply the -changes. Next, open a terminal and run the following: - -``` shell -sudo rm /Library/Preferences/SystemConfiguration/NetworkInterfaces.plist -``` - -Now reboot, and the App Store should work. +There is further advice and information about macOS guests in the +project +[wiki](https://github.com/quickemu-project/quickemu/wiki/03-Create-macOS-virtual-machines#automatically-create-macos-guests). ## [Creating Windows guests](https://github.com/quickemu-project/quickemu/wiki/04-Create-Windows-virtual-machines) 🪟 @@ -441,31 +385,8 @@ quickemu --vm windows-11.conf - Username: `Quickemu` - Password: `quickemu` -### Regional versions - -By default `quickget` will download the *"English International"* -release (*"English (United States)"* for server releases), but you can -optionally specify one of the supported languages: For example: - -``` shell -quickget windows 11 "Chinese (Traditional)" -``` - -The default Windows 11 configuration looks like this: - -``` shell -guest_os="windows" -disk_img="windows-11/disk.qcow2" -iso="windows-11/windows-11.iso" -fixed_iso="windows-11/virtio-win.iso" -tpm="on" -secureboot="off" -``` - -- `guest_os="windows"` instructs `quickemu` to optimise for Windows. -- `fixed_iso=` specifies the ISO image that provides VirtIO drivers. -- `tpm="on"` instructs `quickemu` to create a software emulated TPM - device using `swtpm`. +Further information is available from the project +[wiki](https://github.com/quickemu-project/quickemu/wiki/04-Create-Windows-virtual-machines) # AUTHORS