diff --git a/docs/quickemu.1 b/docs/quickemu.1 index 3abafee..2d9cc2b 100644 --- a/docs/quickemu.1 +++ b/docs/quickemu.1 @@ -1,6 +1,6 @@ -.\" Automatically generated by Pandoc 3.1.13 +.\" Automatically generated by Pandoc 3.2 .\" -.TH "QUICKEMU" "1" "May 9, 2024" "quickemu" "Quickemu User Manual" +.TH "QUICKEMU" "1" "May 13, 2024" "quickemu" "Quickemu User Manual" .SH NAME quickemu \- A quick VM builder and manager .SH SYNOPSIS @@ -261,16 +261,31 @@ EDK II .UE \c .IP \[bu] 2 \c +.UR https://www.gnu.org/software/gawk/ +gawk +.UE \c +.IP \[bu] 2 +\c .UR https://www.gnu.org/software/grep/ grep .UE \c .IP \[bu] 2 \c +.UR https://gitlab.freedesktop.org/mesa/demos +glxinfo +.UE \c +.IP \[bu] 2 +\c .UR https://stedolan.github.io/jq/ jq .UE \c .IP \[bu] 2 \c +.UR https://wiki.linuxfoundation.org/lsb/start +LSB +.UE \c +.IP \[bu] 2 +\c .UR https://github.com/pciutils/pciutils pciutils .UE \c @@ -286,11 +301,6 @@ python3 .UE \c .IP \[bu] 2 \c -.UR https://gist.github.com/MCJack123/943eaca762730ca4b7ae460b731b68e7 -chunkcheck -.UE \c -.IP \[bu] 2 -\c .UR http://cdrtools.sourceforge.net/private/cdrecord.html mkisofs .UE \c @@ -366,17 +376,46 @@ These examples may save a little typing: This also applies to derivatives: .IP .EX -sudo apt install qemu bash coreutils curl ovmf grep jq pciutils procps python3 genisoimage usbutils util\-linux sed socat spice\-client\-gtk libtss2\-tcti\-swtpm0 xdg\-user\-dirs zsync unzip +sudo apt install qemu bash coreutils ovmf grep jq mesa\-utils pciutils 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 pciutils procps python3 genisoimage usbutils util\-linux sed socat spice\-gtk\-tools swtpm xdg\-user\-dirs xrandr unzip +sudo dnf install qemu bash coreutils edk2\-tools grep jq mesa\-demos pciutils procps python3 genisoimage usbutils util\-linux sed socat spice\-gtk\-tools swtpm xdg\-user\-dirs xrandr unzip +.EE +.SS Install requirements on Gentoo +Please note that you may have to use \f[CR]sys\-firmware/edk2\-ovmf\f[R] +instead of \f[CR]sys\-firmware/edk2\-ovmf\-bin\f[R] \- depending on how +your system is configured. +.IP +.EX +sudo emerge \-\-ask \-\-noreplace app\-emulation/qemu \[rs] + app\-shells/bash \[rs] + sys\-apps/coreutils \[rs] + net\-misc/curl \[rs] + sys\-firmware/edk2\-ovmf\-bin \[rs] + sys\-apps/gawk \[rs] + sys\-apps/grep \[rs] + x11\-apps/mesa\-progs \[rs] + app\-misc/jq \[rs] + sys\-apps/pciutils \[rs] + sys\-process/procps \[rs] + app\-cdr/cdrtools \[rs] + sys\-apps/usbutils \[rs] + sys\-apps/util\-linux \[rs] + sys\-apps/sed \[rs] + net\-misc/socat \[rs] + app\-emulation/spice \[rs] + app\-crypt/swtpm \[rs] + x11\-misc/xdg\-user\-dirs \[rs] + x11\-apps/xrandr \[rs] + net\-misc/zsync \[rs] + app\-arch/unzip .EE .SS Install requirements on macOS hosts This is a \f[B]work in progress\f[R] (see \c -.UR https://github.com/quickemu-project/quickemu/issues/248 -issue 248 +.UR https://github.com/quickemu-project/quickemu/issues/447 +issue 447 .UE \c \ for other steps and changes that may enable running on MacOS) .IP @@ -696,6 +735,8 @@ wiki .IP \[bu] 2 \f[CR]slax\f[R] (Slax) .IP \[bu] 2 +\f[CR]slint\f[R] (Slint) +.IP \[bu] 2 \f[CR]slitaz\f[R] (SliTaz) .IP \[bu] 2 \f[CR]solus\f[R] (Solus) @@ -758,11 +799,23 @@ enable copy/paste and USB redirection. Install the SPICE WebDAV agent (\f[CR]spice\-webdavd\f[R]) in the guest to enable file sharing. .RE +.SS Supporting old Linux distros +If you want to run an old Linux , from 2016 or earlier, change the +\f[CR]guest_os\f[R] to \f[CR]linux_old\f[R]. +This will enable the \f[CR]vmware\-svga\f[R] graphics driver which is +better supported on older distros. .SS \c .UR https://github.com/quickemu-project/quickemu/wiki/03-Create-macOS-virtual-machines#automatically-create-macos-guests Creating macOS Guests .UE \c \ 🍏 +\f[B]Installing macOS in a VM can be a bit finicky, if you encounter +problems, \c +.UR https://github.com/quickemu-project/quickemu/discussions +check the Discussions +.UE \c +\ for solutions or ask for help there\f[R] 🛟 +.PP \f[CR]quickget\f[R] automatically downloads a macOS recovery image and creates a virtual machine configuration. .IP @@ -887,8 +940,119 @@ Sur and newer, but not previous releases. And VirtIO Block Media (disks) are supported/stable in Catalina and newer. .RE +.SH 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 +.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 earlier 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]. +.RS 2 +.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 +.RE +.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]. +.SH 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 -There is further advice and information about macOS guests in the +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. +.PP +There may be 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 @@ -977,8 +1141,8 @@ Arguments \-\-display : Select display backend. \[aq]sdl\[aq] (default), \[aq]gtk\[aq], \[aq]none\[aq], \[aq]spice\[aq] or \[aq]spice\-app\[aq] \-\-fullscreen : Starts VM in full screen mode (Ctl+Alt+f to exit) \-\-ignore\-msrs\-always : Configure KVM to always ignore unhandled machine\-specific registers - \-\-screen : Use specified screen to determine the window size. - \-\-screenpct : Percent of fullscreen for VM if \-\-fullscreen is not specified. + \-\-kill : Kill the VM process if it is running + \-\-offline : Override all network settings and start the VM offline \-\-shortcut : Create a desktop shortcut \-\-snapshot apply : Apply/restore a snapshot. \-\-snapshot create : Create a snapshot. @@ -986,8 +1150,8 @@ Arguments \-\-snapshot info : Show disk/snapshot info. \-\-status\-quo : Do not commit any changes to disk/snapshot. \-\-viewer : Choose an alternative viewer. \[at]Options: \[aq]spicy\[aq] (default), \[aq]remote\-viewer\[aq], \[aq]none\[aq] - \-\-width : Set VM screen width. Does nothing without \-\-height - \-\-height : Set VM screen height. Does nothing without \-\-width + \-\-width : Set VM screen width; requires \[aq]\-\-height\[aq] + \-\-height : Set VM screen height; requires \[aq]\-\-width\[aq] \-\-ssh\-port : Set ssh\-port manually \-\-spice\-port : Set spice\-port manually \-\-public\-dir : Expose share directory. \[at]Options: \[aq]\[aq] (default: xdg\-user\-dir PUBLICSHARE), \[aq]\[aq], \[aq]none\[aq] diff --git a/docs/quickemu.1.md b/docs/quickemu.1.md index 2313cf7..a6f6a88 100644 --- a/docs/quickemu.1.md +++ b/docs/quickemu.1.md @@ -1,6 +1,6 @@ --- author: Martin Wimpress -date: May 9, 2024 +date: May 13, 2024 footer: quickemu header: Quickemu User Manual section: 1 @@ -204,12 +204,14 @@ requirements manually: - [Coreutils](https://www.gnu.org/software/coreutils/) - [curl](https://curl.se/) - [EDK II](https://github.com/tianocore/edk2) +- [gawk](https://www.gnu.org/software/gawk/) - [grep](https://www.gnu.org/software/grep/) +- [glxinfo](https://gitlab.freedesktop.org/mesa/demos) - [jq](https://stedolan.github.io/jq/) +- [LSB](https://wiki.linuxfoundation.org/lsb/start) - [pciutils](https://github.com/pciutils/pciutils) - [procps](https://gitlab.com/procps-ng/procps) - [python3](https://www.python.org/) -- [chunkcheck](https://gist.github.com/MCJack123/943eaca762730ca4b7ae460b731b68e7) - [mkisofs](http://cdrtools.sourceforge.net/private/cdrecord.html) - [usbutils](https://github.com/gregkh/usbutils) - [util-linux](https://github.com/karelzak/util-linux) @@ -237,19 +239,50 @@ These examples may save a little typing: This also applies to derivatives: ``` shell -sudo apt install qemu bash coreutils curl ovmf grep jq pciutils procps python3 genisoimage usbutils util-linux sed socat spice-client-gtk libtss2-tcti-swtpm0 xdg-user-dirs zsync unzip +sudo apt install qemu bash coreutils ovmf grep jq mesa-utils pciutils procps python3 genisoimage usbutils util-linux sed socat spice-client-gtk libtss2-tcti-swtpm0 xdg-user-dirs zsync unzip ``` #### Install requirements on Fedora hosts ``` shell -sudo dnf install qemu bash coreutils curl edk2-tools grep jq pciutils procps python3 genisoimage usbutils util-linux sed socat spice-gtk-tools swtpm xdg-user-dirs xrandr unzip +sudo dnf install qemu bash coreutils edk2-tools grep jq mesa-demos pciutils procps python3 genisoimage usbutils util-linux sed socat spice-gtk-tools swtpm xdg-user-dirs xrandr unzip +``` + +### Install requirements on Gentoo + +Please note that you may have to use `sys-firmware/edk2-ovmf` instead of +`sys-firmware/edk2-ovmf-bin` - depending on how your system is +configured. + +``` shell +sudo emerge --ask --noreplace app-emulation/qemu \ + app-shells/bash \ + sys-apps/coreutils \ + net-misc/curl \ + sys-firmware/edk2-ovmf-bin \ + sys-apps/gawk \ + sys-apps/grep \ + x11-apps/mesa-progs \ + app-misc/jq \ + sys-apps/pciutils \ + sys-process/procps \ + app-cdr/cdrtools \ + sys-apps/usbutils \ + sys-apps/util-linux \ + sys-apps/sed \ + net-misc/socat \ + app-emulation/spice \ + app-crypt/swtpm \ + x11-misc/xdg-user-dirs \ + x11-apps/xrandr \ + net-misc/zsync \ + app-arch/unzip ``` #### Install requirements on macOS hosts This is a **work in progress** (see [issue -248](https://github.com/quickemu-project/quickemu/issues/248) for other +447](https://github.com/quickemu-project/quickemu/issues/447) for other steps and changes that may enable running on MacOS) ``` shell @@ -455,6 +488,7 @@ Further information is available from the project - `siduction` (Siduction) - `slackware` (Slackware) - `slax` (Slax) +- `slint` (Slint) - `slitaz` (SliTaz) - `solus` (Solus) - `sparkylinux` (SparkyLinux) @@ -497,8 +531,19 @@ quickemu --vm debian-bullseye.conf - Install the SPICE WebDAV agent (`spice-webdavd`) in the guest to enable file sharing. +## Supporting old Linux distros + +If you want to run an old Linux , from 2016 or earlier, change the +`guest_os` to `linux_old`. This will enable the `vmware-svga` graphics +driver which is better supported on older distros. + ## [Creating macOS Guests](https://github.com/quickemu-project/quickemu/wiki/03-Create-macOS-virtual-machines#automatically-create-macos-guests) 🍏 +**Installing macOS in a VM can be a bit finicky, if you encounter +problems, [check the +Discussions](https://github.com/quickemu-project/quickemu/discussions) +for solutions or ask for help there** 🛟 + `quickget` automatically downloads a macOS recovery image and creates a virtual machine configuration. @@ -592,7 +637,66 @@ macos_release="catalina" - And VirtIO Block Media (disks) are supported/stable in Catalina and newer. -There is further advice and information about macOS guests in the +# 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 earlier 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 may be 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). @@ -649,8 +753,8 @@ Arguments --display : Select display backend. 'sdl' (default), 'gtk', 'none', 'spice' or 'spice-app' --fullscreen : Starts VM in full screen mode (Ctl+Alt+f to exit) --ignore-msrs-always : Configure KVM to always ignore unhandled machine-specific registers - --screen : Use specified screen to determine the window size. - --screenpct : Percent of fullscreen for VM if --fullscreen is not specified. + --kill : Kill the VM process if it is running + --offline : Override all network settings and start the VM offline --shortcut : Create a desktop shortcut --snapshot apply : Apply/restore a snapshot. --snapshot create : Create a snapshot. @@ -658,8 +762,8 @@ Arguments --snapshot info : Show disk/snapshot info. --status-quo : Do not commit any changes to disk/snapshot. --viewer : Choose an alternative viewer. @Options: 'spicy' (default), 'remote-viewer', 'none' - --width : Set VM screen width. Does nothing without --height - --height : Set VM screen height. Does nothing without --width + --width : Set VM screen width; requires '--height' + --height : Set VM screen height; requires '--width' --ssh-port : Set ssh-port manually --spice-port : Set spice-port manually --public-dir : Expose share directory. @Options: '' (default: xdg-user-dir PUBLICSHARE), '', 'none' diff --git a/docs/quickemu_conf.1 b/docs/quickemu_conf.1 index af89843..43c13b9 100644 --- a/docs/quickemu_conf.1 +++ b/docs/quickemu_conf.1 @@ -1,6 +1,6 @@ -.\" Automatically generated by Pandoc 3.1.13 +.\" Automatically generated by Pandoc 3.2 .\" -.TH "QUICKEMU_CONF" "1" "May 9, 2024" "quickemu_conf" "Quickemu Configuration Manual" +.TH "QUICKEMU_CONF" "1" "May 13, 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 f59a703..a1a1170 100644 --- a/docs/quickemu_conf.1.md +++ b/docs/quickemu_conf.1.md @@ -1,6 +1,6 @@ --- author: Martin Wimpress -date: May 9, 2024 +date: May 13, 2024 footer: quickemu_conf header: Quickemu Configuration Manual section: 1 diff --git a/docs/quickget.1 b/docs/quickget.1 index 63d4aef..7dcabdd 100644 --- a/docs/quickget.1 +++ b/docs/quickget.1 @@ -1,6 +1,6 @@ -.\" Automatically generated by Pandoc 3.1.13 +.\" Automatically generated by Pandoc 3.2 .\" -.TH "QUICKGET" "1" "May 9, 2024" "quickget" "Quickget User Manual" +.TH "QUICKGET" "1" "May 13, 2024" "quickget" "Quickget User Manual" .SH NAME quickget \- download and prepare materials for building a quickemu VM .SH SYNOPSIS @@ -281,6 +281,8 @@ wiki .IP \[bu] 2 \f[CR]slax\f[R] (Slax) .IP \[bu] 2 +\f[CR]slint\f[R] (Slint) +.IP \[bu] 2 \f[CR]slitaz\f[R] (SliTaz) .IP \[bu] 2 \f[CR]solus\f[R] (Solus) @@ -343,11 +345,23 @@ enable copy/paste and USB redirection. Install the SPICE WebDAV agent (\f[CR]spice\-webdavd\f[R]) in the guest to enable file sharing. .RE +.SS Supporting old Linux distros +If you want to run an old Linux , from 2016 or earlier, change the +\f[CR]guest_os\f[R] to \f[CR]linux_old\f[R]. +This will enable the \f[CR]vmware\-svga\f[R] graphics driver which is +better supported on older distros. .SS \c .UR https://github.com/quickemu-project/quickemu/wiki/03-Create-macOS-virtual-machines#automatically-create-macos-guests Creating macOS Guests .UE \c \ 🍏 +\f[B]Installing macOS in a VM can be a bit finicky, if you encounter +problems, \c +.UR https://github.com/quickemu-project/quickemu/discussions +check the Discussions +.UE \c +\ for solutions or ask for help there\f[R] 🛟 +.PP \f[CR]quickget\f[R] automatically downloads a macOS recovery image and creates a virtual machine configuration. .IP @@ -472,8 +486,119 @@ Sur and newer, but not previous releases. And VirtIO Block Media (disks) are supported/stable in Catalina and newer. .RE +.SH 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 +.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 earlier 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]. +.RS 2 +.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 +.RE +.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]. +.SH 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 -There is further advice and information about macOS guests in the +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. +.PP +There may be 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 diff --git a/docs/quickget.1.md b/docs/quickget.1.md index c3b2f75..0e94cf5 100644 --- a/docs/quickget.1.md +++ b/docs/quickget.1.md @@ -1,6 +1,6 @@ --- author: Martin Wimpress -date: May 9, 2024 +date: May 13, 2024 footer: quickget header: Quickget User Manual section: 1 @@ -209,6 +209,7 @@ Further information is available from the project - `siduction` (Siduction) - `slackware` (Slackware) - `slax` (Slax) +- `slint` (Slint) - `slitaz` (SliTaz) - `solus` (Solus) - `sparkylinux` (SparkyLinux) @@ -251,8 +252,19 @@ quickemu --vm debian-bullseye.conf - Install the SPICE WebDAV agent (`spice-webdavd`) in the guest to enable file sharing. +## Supporting old Linux distros + +If you want to run an old Linux , from 2016 or earlier, change the +`guest_os` to `linux_old`. This will enable the `vmware-svga` graphics +driver which is better supported on older distros. + ## [Creating macOS Guests](https://github.com/quickemu-project/quickemu/wiki/03-Create-macOS-virtual-machines#automatically-create-macos-guests) 🍏 +**Installing macOS in a VM can be a bit finicky, if you encounter +problems, [check the +Discussions](https://github.com/quickemu-project/quickemu/discussions) +for solutions or ask for help there** 🛟 + `quickget` automatically downloads a macOS recovery image and creates a virtual machine configuration. @@ -346,7 +358,66 @@ macos_release="catalina" - And VirtIO Block Media (disks) are supported/stable in Catalina and newer. -There is further advice and information about macOS guests in the +# 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 earlier 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 may be 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).