oSoWoSo/DistroHopper
1
0
Fork 0
mirror of https://github.com/oSoWoSo/DistroHopper.git synced 2024-08-14 22:46:53 +00:00
Code Issues Projects Releases Packages Wiki Activity

Update README

Browse source
This commit is contained in:
Martin Wimpress 2021-09-28 05:04:30 +01:00
parent b4ec24fa07
commit 818d8ddea1
No known key found for this signature in database
GPG key ID: 61DF940515E06DA3
1 changed files with 172 additions and 118 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

290
README.md
View file

@ -8,7 +8,7 @@
<div align="center"><img src=".github/screenshot.png" alt="Quickemu Screenshot" /></div> <div align="center"><img src=".github/screenshot.png" alt="Quickemu Screenshot" /></div>
<p align="center">Made with 💝 for <img src=".github/tux.png" align="top" width="18" /></p> <p align="center">Made with 💝 for <img src=".github/tux.png" align="top" width="18" /></p>
## Introduction # Introduction
Quickemu is a simple script to *"manage"* Qemu virtual machines. Each virtual Quickemu is a simple script to *"manage"* Qemu virtual machines. Each virtual
machine configuration is a few lines long requiring minimal setup. The machine configuration is a few lines long requiring minimal setup. The
@ -31,19 +31,22 @@ Essential requirements:
* [QEMU](https://www.qemu.org/) 6.0.0 or newer * [QEMU](https://www.qemu.org/) 6.0.0 or newer
* [Coreutils](https://www.gnu.org/software/coreutils/) * [Coreutils](https://www.gnu.org/software/coreutils/)
* [jq](https://stedolan.github.io/jq/)
* [procps](https://gitlab.com/procps-ng/procps) * [procps](https://gitlab.com/procps-ng/procps)
* [usbutils](https://github.com/gregkh/usbutils) * [usbutils](https://github.com/gregkh/usbutils)
* [Wget](https://www.gnu.org/software/wget/) * [Wget](https://www.gnu.org/software/wget/)
* [xrandr](https://gitlab.freedesktop.org/xorg/app/xrandr) * [xrandr](https://gitlab.freedesktop.org/xorg/app/xrandr)
* [zsync](http://zsync.moria.org.uk/)
Optional requirements: Optional requirements:
* `rot13` to *"decrypt"* the macOS OSK key; found in the `bsdgames` package in Debian/Ubuntu * `python3` to run [macrecovery.py](https://github.com/acidanthera/OpenCorePkg/tree/master/Utilities/macrecovery) to download macOS recovery images; provided by `python3-minimal` in Debian/Ubuntu
* `spicy` to connect to VMs via the SPICE protocol; found in the `spice-client-gtk` package in Debian/Ubuntu * `rot13` to *"decrypt"* the macOS OSK key; provided by `bsdgames` in Debian/Ubuntu
* `spicy` to connect to VMs via the SPICE protocol; provided by `spice-client-gtk` in Debian/Ubuntu
## Install Quickemu # Install Quickemu
### Ubuntu ## Ubuntu
Quickemu is available from a PPA for Ubuntu users. The Quickemu PPA also Quickemu is available from a PPA for Ubuntu users. The Quickemu PPA also
includes a back port of QEMU 6.0.0 for 20.04 (Focal) and 21.04 (Hirsute). includes a back port of QEMU 6.0.0 for 20.04 (Focal) and 21.04 (Hirsute).
@ -53,59 +56,141 @@ sudo apt-add-repository ppa:flexiondotorg/quickemu
sudo apt install quickemu sudo apt install quickemu
``` ```
## Usage ## Other Linux
### Linux Guest
* Download a .iso image of a Linux distribution
* Create a VM configuration file; for example `ubuntu.conf`
* The **default** `guest_os` is `linux`, so this is optional for Linux VM configs.
* The `boot` option enables Legacy BIOS (`legacy`) or EFI (`efi`) booting. `legacy` is the default.
```bash ```bash
guest_os="linux" git clone https://github.com/wimpysworld/quickemu
iso="${HOME}/Quickemu/ubuntu/focal-desktop-amd64.iso" cd quickemu
disk_img="${HOME}/Quickemu/ubuntu/focal-desktop-amd64.qcow2"
``` ```
* Use `quickemu` to start the virtual machine: # Usage
## Ubuntu Guest
`quickget` will automatically download an Ubuntu release and also create the
virtual machine configuration.
```bash ```bash
quickemu --vm ubuntu-focal-desktop.conf quickget ubuntu focal
quickemu --vm ubuntu-focal.conf
``` ```
* Complete the installation as normal. * Complete the installation as normal.
* Post-install: * Post-install:
* Install the SPICE agent (`spice-vdagent`) to enable copy/paste and USB redirection * Install the SPICE agent (`spice-vdagent`) to enable copy/paste and USB redirection
* Debian/Ubuntu `sudo apt install spice-vdagent` * `sudo apt install spice-vdagent`
* Install the SPICE WebDAV agent (`spice-webdavd`) to enable file sharing. * Install the SPICE WebDAV agent (`spice-webdavd`) to enable file sharing.
* Debian/Ubuntu `sudo apt install spice-webdavd` * `sudo apt install spice-webdavd`
### Windows 10 Guest ### Ubuntu devel (daily-live) images
You can use `quickemu` to run Windows 10 in a virtual machine. `quickget` can also download/refresh devel images via `zsync` for Ubuntu
developers and testers.
* [Download Windows 10](https://www.microsoft.com/en-gb/software-download/windows10ISO)
* [Download VirtIO drivers for Windows](https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/)
* [Download `spice-webdavd` for Windows](https://www.spice-space.org/download/windows/spice-webdavd/)
* Enables the Windows guest access to shared files on the host.
* [Download UsbDk for Windows](https://www.spice-space.org/download/windows/usbdk/)
* Enables the Windows guest access to redirected USB devices from the host.
* Create a VM configuration file; for example `windows10.conf`
* The `boot` option enables Legacy BIOS (`legacy`) or EFI (`efi`) booting. `legacy` is the default.
* The `guest_os="windows"` line instructs `quickemu` to use optimise for Windows.
```bash ```bash
guest_os="windows" quickget ubuntu devel
iso="${HOME}/Quickemu/windows/Win10_21H1_EnglishInternational_x64.iso" quickemu --vm ubuntu-devel.conf
driver_iso="${HOME}/Quickemu/windows/virtio-win-0.1.208.iso" ```
disk_img="${HOME}/Quickemu/windows/windows.qcow2"
You can run `quickget ubuntu devel` to refresh your daily development image as
often as you like, it will even automatically switch to a new series.
### Ubuntu Flavours
All the official Ubuntu flavours are supported, just replace `ubuntu` with your
preferred flavour.
* `kubuntu`
* `lubuntu`
* `ubuntu-budgie`
* `ubuntu-kylin`
* `ubuntu-mate`
* `ubuntu-studio`
* `xubuntu`
## Linux Guest
* Download a .iso image of a Linux distribution
* Create a VM configuration file; for example `debian-bullseye.conf`
```bash
guest_os="linux"
disk_img="${HOME}/Quickemu/debian-bullseye/disk.qcow2"
iso="${HOME}/Quickemu/debian-bullseye/firmware-11.0.0-amd64-DVD-1.iso"
``` ```
* Use `quickemu` to start the virtual machine: * Use `quickemu` to start the virtual machine:
```bash ```bash
quickemu --vm windows10.conf quickemu --vm debian-bullseye.conf
```
* Complete the installation as normal.
* Post-install:
* Install the SPICE agent (`spice-vdagent`) to enable copy/paste and USB redirection
* Install the SPICE WebDAV agent (`spice-webdavd`) to enable file sharing.
## macOS Guest
`quickget` automatically downloads a macOS recovery image and automatically
creates a virtual machine configuration.
```bash
quickget macos catalina
quickemu --vm macos-catalina.conf
```
macOS `mojave`, `catalina` and `big-sur` are supported.
* Use cursor keys to select the Hard Disk icon
* Click **Disk Utility** and **Continue**
* Select `Apple Inc. VirtIO Block Media` from the list and click **Erase**.
* Enter a `Name:` for the disk and click **Erase**.
* Click **Done**.
* Close Disk Utility
* Click **Reinstall macOS** and **Continue**
* Complete the installation as you normally would.
The default macOS configuration looks like this:
```bash
guest_os="macos"
disk_img="${HOME}/Quickemu/macos-big-sur/RecoveryImage.img"
iso="${HOME}/Quickemu/macos-big-sur/disk.qcow2"
```
* The `guest_os="macos"` line instructs Quickemu to optimise for macOS.
### macOS compatibility
There are some considerations when running macOS via Quickemu.
* `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).
* Supported macOS releases:
* Mojave
* Catalina
* Big Sur
* Optimised by default
* Host CPU vendor is detected and guest CPU configuration is optimised accordingly.
* [VirtIO block device](https://www.kraxel.org/blog/2019/06/macos-qemu-guest/) is used for the system disk (*available since macOS Mojave*).
* [VirtIO `usb-tablet`](http://philjordan.eu/osx-virt/) is used for the mouse (*available since macOS El Capitan*).
* `vmxnet3` network device is used (*available since macOS El Capitan*).
* USB host pass-through is limited to UHCI (USB 2.0)
* Not supported on macOS:
* Copy/paste between the guest and host via SPICE agent.
* File sharing between the guest and host via SPICE webdavd.
* USB passthrough via SPICE.
## Windows 10 Guest
`quickget` automatically downloads [Windows 10](https://www.microsoft.com/en-gb/software-download/windows10ISO),
the [VirtIO drivers for Windows](https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/)
and creates a virtual machine configuration.
```bash
quickget windows 10
quickemu --vm windows-10.conf
``` ```
* During the Windows 10 install you will be asked *"Where do you want to install Windows?"* * During the Windows 10 install you will be asked *"Where do you want to install Windows?"*
@ -118,74 +203,28 @@ quickemu --vm windows10.conf
* Install [spice-webdavd](https://www.spice-space.org/download/windows/spice-webdavd/) * Install [spice-webdavd](https://www.spice-space.org/download/windows/spice-webdavd/)
* Install [UsbDk](https://www.spice-space.org/download/windows/usbdk/) * Install [UsbDk](https://www.spice-space.org/download/windows/usbdk/)
### macOS Guest ### Regional versions
There are some considerations when running macOS via Quickemu. By default `quickget` will download the *"English International"* release, but
you can optionally specify one of the supported languages: For example:
* `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).
* **macOS 10.14.3 or newer is supported**:
* [VirtIO block devices QEMU standard VGA are supported](https://www.kraxel.org/blog/2019/06/macos-qemu-guest/) since macOS 10.14.3 (Mohave).
* [VirtIO `usb-tablet` devices are supported](http://philjordan.eu/osx-virt/) since macOS 10.11 (El Capitan).
* [vmxnet3 network devices are supported](https://github.com/foxlet/macOS-Simple-KVM/blob/master/docs/guide-networking.md) since macOS 10.11 (El Capitan).
* Running macOS on QEMU required the guest CPU is set to `Penryn`.
* This is a very old architecture, [so to unlock higher CPU performance; AVX, AES-NI, SSE et al are enabled](https://www.nicksherlock.com/2017/10/passthrough-of-advanced-cpu-features-for-macos-high-sierra-guests/).
* UHCI USB (USB 2.0) is the fastest supported.
* USB pass-through has not been tested.
* Copy/paste between the guest and host is not supported in macOS.
* File sharing is not supported on macOS.
You can use `quickemu` to run a macOS virtual machine.
* Download macOS using `fetch-macOS-v2.py`
```bash ```bash
wget https://github.com/kholia/OSX-KVM/blob/master/fetch-macOS-v2.py -O fetch-macOS-v2.py quickget windows 10 "Chinese (Traditional)"
python3 ./fetch-macOS-v2.py
``` ```
This will display the following menu. The default Windows 10 configuration looks like this:
```
1. High Sierra (10.13)
2. Mojave (10.14)
3. Catalina (10.15) - RECOMMENDED
4. Latest (Big Sur - 11)
Choose a product to download (1-4):
```
When prompted choose the recommended release.
```
qemu-img convert BaseSystem/BaseSystem.dmg -O raw BaseSystem.img
```
* Create a VM configuration file; for example `macos.conf`
* The `guest_os="macos"` line instructs `quickemu` to use optimise for macOS.
* The `img=` sets the boot disk that you downloaded with `fetch-macOS-v2.py`.
```bash ```bash
guest_os="macos" guest_os="windows"
img="${HOME}/Quickemu/macos/BaseSystem.img" disk_img="${HOME}/Quickemu/windows-10/disk.qcow2"
disk_img="${HOME}/Quickemu/macos/macos.qcow2" iso="${HOME}/Quickemu/windows-10/Win10_21H1_English_x64.iso"
driver_iso="${HOME}/Quickemu/windows-10/virtio-win.iso"
``` ```
* Use `quickemu` to start the virtual machine: * The `guest_os="windows"` line instructs `quickemu` to optimise for Windows.
* The `driver_iso=` line specifies the ISO image that provides VirtIO drivers.
```bash # SPICE
quickemu --vm macos.conf
```
* Boot from the BaseSystem (use cursor keys if the mouse doesn't work)
* Click **Disk Utility** and **Continue**
* Select `Apple Inc. VirtIO Block Media` that is ~65GB from the list and click **Erase**.
* Enter a `Name:` for the disk and click **Erase**.
* Click **Done**.
* Close Disk Utility
* Click **Reinstall macOS** and **Continue**
* Complete the installation as you normally would.
## SPICE
The following features are only available while using the SPICE protocol: The following features are only available while using the SPICE protocol:
@ -198,10 +237,18 @@ the `spicy` client is installed, available from the `spice-client-gtk` package
in Debian/Ubuntu. in Debian/Ubuntu.
```bash ```bash
quickemu --vm ubuntu-focal-desktop.conf --display spice quickemu --vm ubuntu-focal.conf --display spice
``` ```
## Tuning CPU cores, RAM & disks # BIOS and EFI
Since Quickemu 2.1.0 `efi` is the default boot option. If you want to override
this behaviour then add the following line to you VM configuration to enable
legacy BIOS.
* `boot="legacy"` - Enable Legacy BIOS boot
# Tuning CPU cores, RAM & disks
By default, Quickemu will calculate the number of CPUs cores and RAM to allocate By default, Quickemu will calculate the number of CPUs cores and RAM to allocate
to a VM based on the specifications of your host computer. You can override this to a VM based on the specifications of your host computer. You can override this
@ -213,7 +260,7 @@ Add additional lines to your virtual machine configuration:
* `ram="4G"` - Specify the amount of RAM to allocate to the VM * `ram="4G"` - Specify the amount of RAM to allocate to the VM
* `disk="16G"` - Specify the size of the virtual disk allocated to the VM * `disk="16G"` - Specify the size of the virtual disk allocated to the VM
## Network port forwarding # Network port forwarding
Add an additional line to your virtual machine configuration. For example: Add an additional line to your virtual machine configuration. For example:
@ -224,18 +271,18 @@ In the example above:
* Port 8123 on the host is forwarded to port 8123 on the guest. * Port 8123 on the host is forwarded to port 8123 on the guest.
* Port 8888 on the host is forwarded to port 80 on the guest. * Port 8888 on the host is forwarded to port 80 on the guest.
## USB redirection # USB redirection
Quickemu support USB redirection via host passthrough and SPICE passthrough. Quickemu supports USB redirection via SPICE passthrough and host passthrough.
### SPICE redirection ## SPICE redirection (recommended)
Using SPICE for USB passthrough is easiest as it doesn't require any elevated Using SPICE for USB passthrough is easiest as it doesn't require any elevated
permission, start Quickemu with `--display spice` and then select `Input` -> permission, start Quickemu with `--display spice` and then select `Input` ->
`Select USB Device for redirection` from the menu to chose which device(s) you want `Select USB Device for redirection` from the menu to chose which device(s) you want
to attach to the VM. to attach to the guest.
### Host redirection ## Host redirection
**USB host redirection is not recommended**, it is provided purely for backwards **USB host redirection is not recommended**, it is provided purely for backwards
compatibility to older versions of Quickemu. Using SPICE is preferred, see above. compatibility to older versions of Quickemu. Using SPICE is preferred, see above.
@ -255,11 +302,11 @@ commands to modify the USB device(s) access permissions, like this:
``` ```
- USB: Host pass-through requested: - USB: Host pass-through requested:
- Sennheiser Communications EPOS GTW 270 on bus 001 device 005 needs permission changes: - Sennheiser Communications EPOS GTW 270 on bus 001 device 005 needs permission changes:
sudo chown -v root:martin /dev/bus/usb/001/005 sudo chown -v root:user /dev/bus/usb/001/005
ERROR! USB permission changes are required 👆 ERROR! USB permission changes are required 👆
``` ```
## All the options # All the options
Here are the usage instructions: Here are the usage instructions:
@ -288,7 +335,7 @@ Desktop shortcuts can be created for a VM, the shortcuts are saved in `~/.local/
quickemu --vm ubuntu-focal-desktop.conf --shortcut quickemu --vm ubuntu-focal-desktop.conf --shortcut
``` ```
### Screen and window size ## Screen and window size
<ins>Note about screen and window size</ins> <ins>Note about screen and window size</ins>
@ -332,30 +379,37 @@ The above uses the 2560x1440 screen to compute the size of the window, which
Quickemu sizes to 2048x1152. Without the `--screen` option, Quickemu would have Quickemu sizes to 2048x1152. Without the `--screen` option, Quickemu would have
used the 1920x1080 monitor which results in a window size of 1664x936. used the 1920x1080 monitor which results in a window size of 1664x936.
## TODO # TODO
- [ ] Default to EFI booting.
- [ ] Only use video drivers with legacy VGA when legacy boot is enabled.
- [ ] Include macOS compatible firmware.
- [ ] Make default virtual disk capacity suitable for the target guest OS.
- [ ] Optimise macOS guests.
- [ ] Optimise Windows guests.
- [ ] Add BSD support.
- [ ] `spice-app` support via `virt-viewer`.
- [ ] Improve disk management.
- [ ] [Add Faux OEM](https://code.launchpad.net/~ubuntu-installer/ubiquity/+git/ubiquity/+merge/379899).
- [ ] Add 9p support
- [ ] Add `spice-app` support via `virt-viewer`; *requires `virt-viewer` 8.0 or newer*
- [ ] Add support for `ignore_msrs` for macOS. `echo "options kvm ignore_msrs=Y" >> /etc/modprobe.d/kvm.conf && update-initramfs -k all -u`
- [ ] Include macOS compatible firmware
- [ ] Add BSD support
- [ ] Improve disk management
- [ ] [Add Faux OEM](https://code.launchpad.net/~ubuntu-installer/ubiquity/+git/ubiquity/+merge/379899)
# References # References
Useful reference that assisted the development of Quickemu.
* macOS * macOS
* <https://www.nicksherlock.com/2020/06/installing-macos-big-sur-on-proxmox/> * <https://www.nicksherlock.com/2020/06/installing-macos-big-sur-on-proxmox/>
* <https://passthroughpo.st/mac-os-adds-early-support-for-virtio-qemu/>
* <https://github.com/kholia/OSX-KVM> * <https://github.com/kholia/OSX-KVM>
* <https://github.com/thenickdude/KVM-Opencore> * <https://github.com/thenickdude/KVM-Opencore>
* <https://github.com/acidanthera/OpenCorePkg/tree/master/Utilities/macrecovery> * <https://github.com/acidanthera/OpenCorePkg/tree/master/Utilities/macrecovery>
* <https://www.kraxel.org/blog/2017/09/running-macos-as-guest-in-kvm/> * <https://www.kraxel.org/blog/2017/09/running-macos-as-guest-in-kvm/>
* <https://www.nicksherlock.com/2017/10/passthrough-of-advanced-cpu-features-for-macos-high-sierra-guests/>
* <http://philjordan.eu/osx-virt/>
* <https://github.com/Dids/clover-builder> * <https://github.com/Dids/clover-builder>
* Windows * Windows
* <https://www.heiko-sieger.info/running-windows-10-on-linux-using-kvm-with-vga-passthrough/> * <https://www.heiko-sieger.info/running-windows-10-on-linux-using-kvm-with-vga-passthrough/>
* <https://leduccc.medium.com/improving-the-performance-of-a-windows-10-guest-on-qemu-a5b3f54d9cf5> * <https://leduccc.medium.com/improving-the-performance-of-a-windows-10-guest-on-qemu-a5b3f54d9cf5>
* <https://frontpagelinux.com/tutorials/how-to-use-linux-kvm-to-optimize-your-windows-10-virtual-machine/> * <https://frontpagelinux.com/tutorials/how-to-use-linux-kvm-to-optimize-your-windows-10-virtual-machine/>
* <https://github.com/pbatard/Fido>
* 9p & virtiofs
* <https://wiki.qemu.org/Documentation/9psetup>
* <https://www.linux-kvm.org/page/9p_virtio>
* <https://superuser.com/questions/628169/how-to-share-a-directory-with-the-host-without-networking-in-qemu>
* <https://virtio-fs.gitlab.io/>