RomanNum3ral
/
quickemu
mirror of https://github.com/quickemu-project/quickemu.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: regenerated man pages 

includes some updates and changes from wiki including
contribution of Gentoo guidance
This commit is contained in:
Phil Clifford 2024-05-13 02:20:57 +01:00 committed by Martin Wimpress
parent ea92320fe4
commit 212450765b
6 changed files with 498 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

196
docs/quickemu.1
View File

@ -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 .SH NAME
quickemu \- A quick VM builder and manager quickemu \- A quick VM builder and manager
.SH SYNOPSIS .SH SYNOPSIS
@ -261,16 +261,31 @@ EDK II
.UE \c .UE \c
.IP \[bu] 2 .IP \[bu] 2
\c \c
.UR https://www.gnu.org/software/gawk/
gawk
.UE \c
.IP \[bu] 2
\c
.UR https://www.gnu.org/software/grep/ .UR https://www.gnu.org/software/grep/
grep grep
.UE \c .UE \c
.IP \[bu] 2 .IP \[bu] 2
\c \c
.UR https://gitlab.freedesktop.org/mesa/demos
glxinfo
.UE \c
.IP \[bu] 2
\c
.UR https://stedolan.github.io/jq/ .UR https://stedolan.github.io/jq/
jq jq
.UE \c .UE \c
.IP \[bu] 2 .IP \[bu] 2
\c \c
.UR https://wiki.linuxfoundation.org/lsb/start
LSB
.UE \c
.IP \[bu] 2
\c
.UR https://github.com/pciutils/pciutils .UR https://github.com/pciutils/pciutils
pciutils pciutils
.UE \c .UE \c
@ -286,11 +301,6 @@ python3
.UE \c .UE \c
.IP \[bu] 2 .IP \[bu] 2
\c \c
.UR https://gist.github.com/MCJack123/943eaca762730ca4b7ae460b731b68e7
chunkcheck
.UE \c
.IP \[bu] 2
\c
.UR http://cdrtools.sourceforge.net/private/cdrecord.html .UR http://cdrtools.sourceforge.net/private/cdrecord.html
mkisofs mkisofs
.UE \c .UE \c
@ -366,17 +376,46 @@ These examples may save a little typing:
This also applies to derivatives: This also applies to derivatives:
.IP .IP
.EX .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 .EE
.SS Install requirements on Fedora hosts .SS Install requirements on Fedora hosts
.IP .IP
.EX .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 .EE
.SS Install requirements on macOS hosts .SS Install requirements on macOS hosts
This is a \f[B]work in progress\f[R] (see \c This is a \f[B]work in progress\f[R] (see \c
.UR https://github.com/quickemu-project/quickemu/issues/248 .UR https://github.com/quickemu-project/quickemu/issues/447
issue 248 issue 447
.UE \c .UE \c
\ for other steps and changes that may enable running on MacOS) \ for other steps and changes that may enable running on MacOS)
.IP .IP
@ -696,6 +735,8 @@ wiki
.IP \[bu] 2 .IP \[bu] 2
\f[CR]slax\f[R] (Slax) \f[CR]slax\f[R] (Slax)
.IP \[bu] 2 .IP \[bu] 2
\f[CR]slint\f[R] (Slint)
.IP \[bu] 2
\f[CR]slitaz\f[R] (SliTaz) \f[CR]slitaz\f[R] (SliTaz)
.IP \[bu] 2 .IP \[bu] 2
\f[CR]solus\f[R] (Solus) \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 Install the SPICE WebDAV agent (\f[CR]spice\-webdavd\f[R]) in the guest
to enable file sharing. to enable file sharing.
.RE .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 .SS \c
.UR https://github.com/quickemu-project/quickemu/wiki/03-Create-macOS-virtual-machines#automatically-create-macos-guests .UR https://github.com/quickemu-project/quickemu/wiki/03-Create-macOS-virtual-machines#automatically-create-macos-guests
Creating macOS Guests Creating macOS Guests
.UE \c .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 \f[CR]quickget\f[R] automatically downloads a macOS recovery image and
creates a virtual machine configuration. creates a virtual machine configuration.
.IP .IP
@ -887,8 +940,119 @@ Sur and newer, but not previous releases.
And VirtIO Block Media (disks) are supported/stable in Catalina and And VirtIO Block Media (disks) are supported/stable in Catalina and
newer. newer.
.RE .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 .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 project \c
.UR https://github.com/quickemu-project/quickemu/wiki/03-Create-macOS-virtual-machines#automatically-create-macos-guests .UR https://github.com/quickemu-project/quickemu/wiki/03-Create-macOS-virtual-machines#automatically-create-macos-guests
wiki 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] \-\-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) \-\-fullscreen : Starts VM in full screen mode (Ctl+Alt+f to exit)
\-\-ignore\-msrs\-always : Configure KVM to always ignore unhandled machine\-specific registers \-\-ignore\-msrs\-always : Configure KVM to always ignore unhandled machine\-specific registers
\-\-screen <screen> : Use specified screen to determine the window size. \-\-kill : Kill the VM process if it is running
\-\-screenpct <percent> : Percent of fullscreen for VM if \-\-fullscreen is not specified. \-\-offline : Override all network settings and start the VM offline
\-\-shortcut : Create a desktop shortcut \-\-shortcut : Create a desktop shortcut
\-\-snapshot apply <tag> : Apply/restore a snapshot. \-\-snapshot apply <tag> : Apply/restore a snapshot.
\-\-snapshot create <tag> : Create a snapshot. \-\-snapshot create <tag> : Create a snapshot.
@ -986,8 +1150,8 @@ Arguments
\-\-snapshot info : Show disk/snapshot info. \-\-snapshot info : Show disk/snapshot info.
\-\-status\-quo : Do not commit any changes to disk/snapshot. \-\-status\-quo : Do not commit any changes to disk/snapshot.
\-\-viewer <viewer> : Choose an alternative viewer. \[at]Options: \[aq]spicy\[aq] (default), \[aq]remote\-viewer\[aq], \[aq]none\[aq] \-\-viewer <viewer> : Choose an alternative viewer. \[at]Options: \[aq]spicy\[aq] (default), \[aq]remote\-viewer\[aq], \[aq]none\[aq]
\-\-width <width> : Set VM screen width. Does nothing without \-\-height \-\-width <width> : Set VM screen width; requires \[aq]\-\-height\[aq]
\-\-height <height> : Set VM screen height. Does nothing without \-\-width \-\-height <height> : Set VM screen height; requires \[aq]\-\-width\[aq]
\-\-ssh\-port <port> : Set ssh\-port manually \-\-ssh\-port <port> : Set ssh\-port manually
\-\-spice\-port <port> : Set spice\-port manually \-\-spice\-port <port> : Set spice\-port manually
\-\-public\-dir <path> : Expose share directory. \[at]Options: \[aq]\[aq] (default: xdg\-user\-dir PUBLICSHARE), \[aq]<directory>\[aq], \[aq]none\[aq] \-\-public\-dir <path> : Expose share directory. \[at]Options: \[aq]\[aq] (default: xdg\-user\-dir PUBLICSHARE), \[aq]<directory>\[aq], \[aq]none\[aq]

124
docs/quickemu.1.md
View File

@ -1,6 +1,6 @@
--- ---
author: Martin Wimpress author: Martin Wimpress
date: May 9, 2024 date: May 13, 2024
footer: quickemu footer: quickemu
header: Quickemu User Manual header: Quickemu User Manual
section: 1 section: 1
@ -204,12 +204,14 @@ requirements manually:
- [Coreutils](https://www.gnu.org/software/coreutils/) - [Coreutils](https://www.gnu.org/software/coreutils/)
- [curl](https://curl.se/) - [curl](https://curl.se/)
- [EDK II](https://github.com/tianocore/edk2) - [EDK II](https://github.com/tianocore/edk2)
- [gawk](https://www.gnu.org/software/gawk/)
- [grep](https://www.gnu.org/software/grep/) - [grep](https://www.gnu.org/software/grep/)
- [glxinfo](https://gitlab.freedesktop.org/mesa/demos)
- [jq](https://stedolan.github.io/jq/) - [jq](https://stedolan.github.io/jq/)
- [LSB](https://wiki.linuxfoundation.org/lsb/start)
- [pciutils](https://github.com/pciutils/pciutils) - [pciutils](https://github.com/pciutils/pciutils)
- [procps](https://gitlab.com/procps-ng/procps) - [procps](https://gitlab.com/procps-ng/procps)
- [python3](https://www.python.org/) - [python3](https://www.python.org/)
- [chunkcheck](https://gist.github.com/MCJack123/943eaca762730ca4b7ae460b731b68e7)
- [mkisofs](http://cdrtools.sourceforge.net/private/cdrecord.html) - [mkisofs](http://cdrtools.sourceforge.net/private/cdrecord.html)
- [usbutils](https://github.com/gregkh/usbutils) - [usbutils](https://github.com/gregkh/usbutils)
- [util-linux](https://github.com/karelzak/util-linux) - [util-linux](https://github.com/karelzak/util-linux)
@ -237,19 +239,50 @@ These examples may save a little typing:
This also applies to derivatives: This also applies to derivatives:
``` shell ``` 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 #### Install requirements on Fedora hosts
``` shell ``` 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 #### Install requirements on macOS hosts
This is a **work in progress** (see [issue 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) steps and changes that may enable running on MacOS)
``` shell ``` shell
@ -455,6 +488,7 @@ Further information is available from the project
- `siduction` (Siduction) - `siduction` (Siduction)
- `slackware` (Slackware) - `slackware` (Slackware)
- `slax` (Slax) - `slax` (Slax)
- `slint` (Slint)
- `slitaz` (SliTaz) - `slitaz` (SliTaz)
- `solus` (Solus) - `solus` (Solus)
- `sparkylinux` (SparkyLinux) - `sparkylinux` (SparkyLinux)
@ -497,8 +531,19 @@ quickemu --vm debian-bullseye.conf
- Install the SPICE WebDAV agent (`spice-webdavd`) in the guest to - Install the SPICE WebDAV agent (`spice-webdavd`) in the guest to
enable file sharing. 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) 🍏 ## [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 `quickget` automatically downloads a macOS recovery image and creates a
virtual machine configuration. virtual machine configuration.
@ -592,7 +637,66 @@ macos_release="catalina"
- And VirtIO Block Media (disks) are supported/stable in Catalina - And VirtIO Block Media (disks) are supported/stable in Catalina
and newer. 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 project
[wiki](https://github.com/quickemu-project/quickemu/wiki/03-Create-macOS-virtual-machines#automatically-create-macos-guests). [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' --display : Select display backend. 'sdl' (default), 'gtk', 'none', 'spice' or 'spice-app'
--fullscreen : Starts VM in full screen mode (Ctl+Alt+f to exit) --fullscreen : Starts VM in full screen mode (Ctl+Alt+f to exit)
--ignore-msrs-always : Configure KVM to always ignore unhandled machine-specific registers --ignore-msrs-always : Configure KVM to always ignore unhandled machine-specific registers
--screen <screen> : Use specified screen to determine the window size. --kill : Kill the VM process if it is running
--screenpct <percent> : Percent of fullscreen for VM if --fullscreen is not specified. --offline : Override all network settings and start the VM offline
--shortcut : Create a desktop shortcut --shortcut : Create a desktop shortcut
--snapshot apply <tag> : Apply/restore a snapshot. --snapshot apply <tag> : Apply/restore a snapshot.
--snapshot create <tag> : Create a snapshot. --snapshot create <tag> : Create a snapshot.
@ -658,8 +762,8 @@ Arguments
--snapshot info : Show disk/snapshot info. --snapshot info : Show disk/snapshot info.
--status-quo : Do not commit any changes to disk/snapshot. --status-quo : Do not commit any changes to disk/snapshot.
--viewer <viewer> : Choose an alternative viewer. @Options: 'spicy' (default), 'remote-viewer', 'none' --viewer <viewer> : Choose an alternative viewer. @Options: 'spicy' (default), 'remote-viewer', 'none'
--width <width> : Set VM screen width. Does nothing without --height --width <width> : Set VM screen width; requires '--height'
--height <height> : Set VM screen height. Does nothing without --width --height <height> : Set VM screen height; requires '--width'
--ssh-port <port> : Set ssh-port manually --ssh-port <port> : Set ssh-port manually
--spice-port <port> : Set spice-port manually --spice-port <port> : Set spice-port manually
--public-dir <path> : Expose share directory. @Options: '' (default: xdg-user-dir PUBLICSHARE), '<directory>', 'none' --public-dir <path> : Expose share directory. @Options: '' (default: xdg-user-dir PUBLICSHARE), '<directory>', 'none'

4
docs/quickemu_conf.1
View File

@ -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 .SH NAME
quickemu_conf \- Options and parameters in the quickemu <vm>.conf quickemu_conf \- Options and parameters in the quickemu <vm>.conf
.SH DESCRIPTION .SH DESCRIPTION

2
docs/quickemu_conf.1.md
View File

@ -1,6 +1,6 @@
--- ---
author: Martin Wimpress author: Martin Wimpress
date: May 9, 2024 date: May 13, 2024
footer: quickemu_conf footer: quickemu_conf
header: Quickemu Configuration Manual header: Quickemu Configuration Manual
section: 1 section: 1

131
docs/quickget.1
View File

@ -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 .SH NAME
quickget \- download and prepare materials for building a quickemu VM quickget \- download and prepare materials for building a quickemu VM
.SH SYNOPSIS .SH SYNOPSIS
@ -281,6 +281,8 @@ wiki
.IP \[bu] 2 .IP \[bu] 2
\f[CR]slax\f[R] (Slax) \f[CR]slax\f[R] (Slax)
.IP \[bu] 2 .IP \[bu] 2
\f[CR]slint\f[R] (Slint)
.IP \[bu] 2
\f[CR]slitaz\f[R] (SliTaz) \f[CR]slitaz\f[R] (SliTaz)
.IP \[bu] 2 .IP \[bu] 2
\f[CR]solus\f[R] (Solus) \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 Install the SPICE WebDAV agent (\f[CR]spice\-webdavd\f[R]) in the guest
to enable file sharing. to enable file sharing.
.RE .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 .SS \c
.UR https://github.com/quickemu-project/quickemu/wiki/03-Create-macOS-virtual-machines#automatically-create-macos-guests .UR https://github.com/quickemu-project/quickemu/wiki/03-Create-macOS-virtual-machines#automatically-create-macos-guests
Creating macOS Guests Creating macOS Guests
.UE \c .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 \f[CR]quickget\f[R] automatically downloads a macOS recovery image and
creates a virtual machine configuration. creates a virtual machine configuration.
.IP .IP
@ -472,8 +486,119 @@ Sur and newer, but not previous releases.
And VirtIO Block Media (disks) are supported/stable in Catalina and And VirtIO Block Media (disks) are supported/stable in Catalina and
newer. newer.
.RE .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 .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 project \c
.UR https://github.com/quickemu-project/quickemu/wiki/03-Create-macOS-virtual-machines#automatically-create-macos-guests .UR https://github.com/quickemu-project/quickemu/wiki/03-Create-macOS-virtual-machines#automatically-create-macos-guests
wiki wiki

75
docs/quickget.1.md
View File

@ -1,6 +1,6 @@
--- ---
author: Martin Wimpress author: Martin Wimpress
date: May 9, 2024 date: May 13, 2024
footer: quickget footer: quickget
header: Quickget User Manual header: Quickget User Manual
section: 1 section: 1
@ -209,6 +209,7 @@ Further information is available from the project
- `siduction` (Siduction) - `siduction` (Siduction)
- `slackware` (Slackware) - `slackware` (Slackware)
- `slax` (Slax) - `slax` (Slax)
- `slint` (Slint)
- `slitaz` (SliTaz) - `slitaz` (SliTaz)
- `solus` (Solus) - `solus` (Solus)
- `sparkylinux` (SparkyLinux) - `sparkylinux` (SparkyLinux)
@ -251,8 +252,19 @@ quickemu --vm debian-bullseye.conf
- Install the SPICE WebDAV agent (`spice-webdavd`) in the guest to - Install the SPICE WebDAV agent (`spice-webdavd`) in the guest to
enable file sharing. 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) 🍏 ## [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 `quickget` automatically downloads a macOS recovery image and creates a
virtual machine configuration. virtual machine configuration.
@ -346,7 +358,66 @@ macos_release="catalina"
- And VirtIO Block Media (disks) are supported/stable in Catalina - And VirtIO Block Media (disks) are supported/stable in Catalina
and newer. 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 project
[wiki](https://github.com/quickemu-project/quickemu/wiki/03-Create-macOS-virtual-machines#automatically-create-macos-guests). [wiki](https://github.com/quickemu-project/quickemu/wiki/03-Create-macOS-virtual-machines#automatically-create-macos-guests).