docs: add display compatibility, multiscreen, multiple VMs, Windows scripts, and iPhone passthrough
- Add display backend and VirGL acceleration compatibility table (#1448) - Document max_outputs for multiscreen support (#518) - Add guide for managing multiple VMs from the same OS image (#1282) - Document Windows VM startup script customisation (#1665) - Add experimental iPhone USB passthrough guide for macOS VMs (#468) Resolves: #1665, #1448, #1282, #518 Partially addresses: #468
Martin Wimpress
parent
0bab63a8ac
commit
eb01792ca8
|
|
@ -141,3 +141,94 @@ sudo rm /Library/Preferences/SystemConfiguration/NetworkInterfaces.plist
|
|||
```
|
||||
|
||||
Now reboot, and the App Store should work.
|
||||
|
||||
# iPhone USB passthrough (Experimental)
|
||||
|
||||
Connecting an iPhone to a macOS VM for Xcode development is possible but requires additional configuration. This is an experimental feature with varying success rates depending on your hardware and host Linux distribution.
|
||||
|
||||
**Important**: This process is complex and may not work reliably. Consider it experimental and unsupported. For production iOS development, a physical Mac is recommended.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- A Linux host (not macOS host)
|
||||
- iPhone (iPads have lower success rates)
|
||||
- USB cable (direct connection, not through a hub)
|
||||
- Desktop computer (laptops report more issues)
|
||||
|
||||
## Host configuration
|
||||
|
||||
### 1. Create udev rules for iPhone access
|
||||
|
||||
Create a udev rule to allow access to iPhone USB devices:
|
||||
|
||||
```shell
|
||||
sudo nano /etc/udev/rules.d/97-iphone.rules
|
||||
```
|
||||
|
||||
Add this line (replace `your-group` with your user's primary group):
|
||||
|
||||
```text
|
||||
SUBSYSTEMS=="usb", ATTRS{idVendor}=="05ac", ATTRS{idProduct}=="*", GROUP="your-group", MODE="0660"
|
||||
```
|
||||
|
||||
Reload the udev rules:
|
||||
|
||||
```shell
|
||||
sudo udevadm control --reload-rules
|
||||
```
|
||||
|
||||
### 2. Stop conflicting services
|
||||
|
||||
The host's `usbmuxd` service will compete for the iPhone. Stop and disable it:
|
||||
|
||||
```shell
|
||||
sudo systemctl stop usbmuxd
|
||||
sudo systemctl mask usbmuxd
|
||||
```
|
||||
|
||||
On some distributions, also stop:
|
||||
|
||||
```shell
|
||||
sudo killall gvfs-afc-volume-monitor 2>/dev/null
|
||||
```
|
||||
|
||||
## VM configuration
|
||||
|
||||
Add the iPhone to your macOS VM configuration:
|
||||
|
||||
```shell
|
||||
guest_os="macos"
|
||||
disk_img="macos-sonoma/disk.qcow2"
|
||||
img="macos-sonoma/RecoveryImage.img"
|
||||
macos_release="sonoma"
|
||||
display="gtk"
|
||||
usb_devices=("05ac:12a8")
|
||||
```
|
||||
|
||||
**Note**: The product ID `12a8` is common for iPhones, but yours may differ. Find your iPhone's ID with:
|
||||
|
||||
```shell
|
||||
lsusb | grep -i apple
|
||||
```
|
||||
|
||||
## Limitations
|
||||
|
||||
- **Disconnect/reconnect loops**: The iPhone may repeatedly disconnect and reconnect. Enabling flight mode on the iPhone sometimes helps
|
||||
- **Trust dialog timing**: You may need to quickly tap "Trust" on the iPhone when the dialog appears
|
||||
- **Xcode detection**: Even when connected, Xcode may not detect the device reliably
|
||||
- **iPads**: Generally have lower success rates than iPhones
|
||||
|
||||
## Alternative: Wireless debugging
|
||||
|
||||
For a more reliable workflow, consider using Xcode's wireless debugging feature instead of USB passthrough. After pairing the device once on a physical Mac, you can use wireless debugging from the VM.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If you see `LIBUSB_ERROR_NOT_FOUND` or "Device is in use by another application":
|
||||
|
||||
1. Verify `usbmuxd` is stopped: `systemctl status usbmuxd`
|
||||
2. Check no other process has claimed the device: `lsof /dev/bus/usb/*/*`
|
||||
3. Try a different USB port (USB 2.0 ports sometimes work better)
|
||||
4. Reboot the host and try again
|
||||
|
||||
For detailed troubleshooting and community solutions, see [issue #468](https://github.com/quickemu-project/quickemu/issues/468).
|
||||
|
|
|
|||
|
|
@ -64,6 +64,78 @@ cpu_cores="4"
|
|||
|
||||
See [PR #1797](https://github.com/quickemu-project/quickemu/pull/1797) for implementation details.
|
||||
|
||||
# Customising Windows VM startup
|
||||
|
||||
When `quickget` downloads Windows 10 or 11, it creates an unattended installation that automatically configures the VM. You can customise this process by modifying the `autounattend.xml` file.
|
||||
|
||||
## Adding custom startup scripts
|
||||
|
||||
The unattended installation includes a `FirstLogonCommands` section that runs commands after the first user login. To add your own scripts:
|
||||
|
||||
1. Locate the unattended files in your VM directory:
|
||||
|
||||
```shell
|
||||
ls windows-11/unattended/
|
||||
```
|
||||
|
||||
2. Edit `autounattend.xml` and find the `FirstLogonCommands` section (near the end of the file)
|
||||
|
||||
3. Add your custom commands. Each command needs an `Order` number (higher numbers run later):
|
||||
|
||||
```xml
|
||||
<FirstLogonCommands>
|
||||
<!-- Existing commands are here with Order 1-7 -->
|
||||
|
||||
<SynchronousCommand wcm:action="add">
|
||||
<CommandLine>powershell -ExecutionPolicy Bypass -File F:\setup.ps1</CommandLine>
|
||||
<Description>Run custom setup script</Description>
|
||||
<Order>8</Order>
|
||||
</SynchronousCommand>
|
||||
</FirstLogonCommands>
|
||||
```
|
||||
|
||||
4. Place your script in the `unattended/` directory so it's included in the ISO
|
||||
|
||||
5. Regenerate the unattended ISO:
|
||||
|
||||
```shell
|
||||
mkisofs -quiet -J -o windows-11/unattended.iso windows-11/unattended/
|
||||
```
|
||||
|
||||
## Drive letter reference
|
||||
|
||||
During Windows installation, drives are assigned as follows:
|
||||
|
||||
- **C:** - Windows system drive
|
||||
- **E:** - VirtIO drivers ISO (`virtio-win.iso`)
|
||||
- **F:** - Unattended configuration ISO (`unattended.iso`)
|
||||
|
||||
## Disabling unattended installation
|
||||
|
||||
To perform a manual Windows installation instead:
|
||||
|
||||
```shell
|
||||
quickget windows 11 --disable-unattended
|
||||
```
|
||||
|
||||
This skips creating the `autounattend.xml` and related files, allowing you to configure Windows manually during installation.
|
||||
|
||||
## Starting fresh
|
||||
|
||||
To regenerate the default unattended configuration after making changes:
|
||||
|
||||
1. Delete the existing unattended files:
|
||||
|
||||
```shell
|
||||
rm -rf windows-11/unattended/ windows-11/unattended.iso
|
||||
```
|
||||
|
||||
2. Re-run quickget (it will recreate the unattended files):
|
||||
|
||||
```shell
|
||||
quickget windows 11
|
||||
```
|
||||
|
||||
# Known Issues
|
||||
|
||||
## SPICE display causes freezes
|
||||
|
|
|
|||
|
|
@ -148,6 +148,39 @@ This can be overridden by setting `width` and `height` in the VM configuration f
|
|||
quickemu --vm ubuntu-22.04-desktop.conf --width 1920 --height 1080
|
||||
```
|
||||
|
||||
## Display backend and GPU acceleration
|
||||
|
||||
Quickemu selects the display device based on the guest OS and the `--display` option. **Not all combinations support GPU acceleration (VirGL).**
|
||||
|
||||
GPU acceleration via VirGL requires the `virtio-vga` or `virtio-vga-gl` device, which is only available with certain display backends:
|
||||
|
||||
| Guest OS | Display Backend | GPU Device | VirGL Acceleration |
|
||||
|----------|-----------------|------------|-------------------|
|
||||
| Linux | `sdl` (default) | virtio-vga | Yes |
|
||||
| Linux | `gtk` | virtio-vga | Yes |
|
||||
| Linux | `spice-app` | virtio-vga | Yes |
|
||||
| Linux | `spice` | virtio-gpu | No |
|
||||
| Linux | `none` | virtio-gpu | No |
|
||||
| Windows | `sdl` (default) | virtio-vga | Yes |
|
||||
| Windows | `cocoa` | virtio-vga | Yes |
|
||||
| Windows | `spice-app` | virtio-vga | Yes |
|
||||
| Windows | `gtk` | qxl-vga | No |
|
||||
| Windows | `spice` | qxl-vga | No |
|
||||
| macOS | All | VGA | No |
|
||||
| BSD | All | VGA | No |
|
||||
|
||||
**Recommendation**: For best graphics performance on Linux guests, use `--display sdl` (the default). If you need SPICE features like clipboard sharing and USB redirection, be aware that `--display spice` disables VirGL acceleration.
|
||||
|
||||
## Multiscreen support
|
||||
|
||||
To enable multiple virtual monitors, add the `max_outputs` option to your VM configuration file:
|
||||
|
||||
```shell
|
||||
max_outputs="2"
|
||||
```
|
||||
|
||||
This configures the virtual GPU to support up to the specified number of displays. The actual behaviour depends on your display backend and guest OS support.
|
||||
|
||||
## macOS display resolutions
|
||||
|
||||
To set the display resolution on macOS, you will also need to install a 3rd party resolution manager in the macOS VM to get the best results. We recommended using one of the following:
|
||||
|
|
@ -347,6 +380,67 @@ like this:
|
|||
Since Quickemu 2.2.0 a software emulated TPM device can be added to guest virtual machines.
|
||||
Just add `tpm="on"` to your VM configuration; **`quickget` will automatically add this line to Windows 11 virtual machines.**
|
||||
|
||||
# Managing multiple VMs from the same OS
|
||||
|
||||
You can create multiple independent VMs from a single downloaded ISO image. Each VM needs its own configuration file and disk image.
|
||||
|
||||
## Creating additional VMs
|
||||
|
||||
1. Copy the original configuration file with a new name:
|
||||
|
||||
```shell
|
||||
cp ubuntu-24.04.conf ubuntu-24.04-testing.conf
|
||||
```
|
||||
|
||||
2. Edit the new configuration to use a different disk image path:
|
||||
|
||||
```shell
|
||||
guest_os="linux"
|
||||
disk_img="ubuntu-24.04-testing/disk.qcow2"
|
||||
iso="ubuntu-24.04/ubuntu-24.04.iso"
|
||||
```
|
||||
|
||||
3. Create the directory for the new VM:
|
||||
|
||||
```shell
|
||||
mkdir ubuntu-24.04-testing
|
||||
```
|
||||
|
||||
4. Start the new VM - quickemu will create a fresh disk image:
|
||||
|
||||
```shell
|
||||
quickemu --vm ubuntu-24.04-testing.conf
|
||||
```
|
||||
|
||||
**Important**: Each VM must have a unique `disk_img` path. The ISO can be shared between configurations since it's read-only during installation.
|
||||
|
||||
## Recommended directory structure
|
||||
|
||||
For managing multiple VMs of the same OS, consider this structure:
|
||||
|
||||
```text
|
||||
~/quickemu/
|
||||
├── ubuntu-24.04/
|
||||
│ ├── ubuntu-24.04.iso # Shared ISO
|
||||
│ └── disk.qcow2 # Primary VM disk
|
||||
├── ubuntu-24.04-dev/
|
||||
│ └── disk.qcow2 # Development VM disk
|
||||
├── ubuntu-24.04-testing/
|
||||
│ └── disk.qcow2 # Testing VM disk
|
||||
├── ubuntu-24.04.conf # Primary VM config
|
||||
├── ubuntu-24.04-dev.conf # Development VM config
|
||||
└── ubuntu-24.04-testing.conf # Testing VM config
|
||||
```
|
||||
|
||||
Each configuration file points to its respective disk image while sharing the same ISO:
|
||||
|
||||
```shell
|
||||
# ubuntu-24.04-dev.conf
|
||||
guest_os="linux"
|
||||
disk_img="ubuntu-24.04-dev/disk.qcow2"
|
||||
iso="ubuntu-24.04/ubuntu-24.04.iso"
|
||||
```
|
||||
|
||||
# Desktop shortcuts
|
||||
|
||||
Desktop shortcuts can be created for a VM, the shortcuts are saved in `~/.local/share/applications`. Here is an example of how to create a
|
||||
|
|
|
|||
Loading…
Reference in New Issue