diff --git a/03-Create-macOS-virtual-machines.md b/03-Create-macOS-virtual-machines.md index 9fb874e..62d2d56 100644 --- a/03-Create-macOS-virtual-machines.md +++ b/03-Create-macOS-virtual-machines.md @@ -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). diff --git a/04-Create-Windows-virtual-machines.md b/04-Create-Windows-virtual-machines.md index c037c93..cab88f1 100644 --- a/04-Create-Windows-virtual-machines.md +++ b/04-Create-Windows-virtual-machines.md @@ -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 + + + + + powershell -ExecutionPolicy Bypass -File F:\setup.ps1 + Run custom setup script + 8 + + +``` + +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 diff --git a/05-Advanced-quickemu-configuration.md b/05-Advanced-quickemu-configuration.md index a19541c..3dfc092 100644 --- a/05-Advanced-quickemu-configuration.md +++ b/05-Advanced-quickemu-configuration.md @@ -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