Companion VM Setup

The USB of the emulated iPhone cannot connect to the host computer at the moment.

Instead, it connects to another VM running on the same machine (via UNIX socket or TCP) or another machine (via TCP).

The remote USB solution has the following settings:

• On the iPhone, specified in the -M flag:
  • usb-conn-type: unix (default), ipv4, or ipv6. self-explanatory.
  • usb-conn-addr: Path or IP address, UNIX socket uses path. UNIX sockets are not supported on Windows.
  • usb-conn-port: Server port. Only applicable for ipv4 and ipv6.
  • examples: no specification (uses default), -M t8030,...,usb-conn-type=ipv4,usb-conn-addr=127.0.0.1,usb-conn-port=8030
• On the companion VM, using -device usb-tcp-remote:
  • same as the iPhone, but without the usb- prefix.
  • examples: -usb -device usb-ehci,id=ehci -device usb-tcp-remote,bus=ehci.0, -usb -device usb-ehci,id=ehci -device usb-tcp-remote,conn-type=ipv4,conn-addr=127.0.0.1,conn-port=8030,bus=ehci.0

Caution

The companion VM must always be started before the emulated iPhone, otherwise no USB connection is established.

VM Setup

Set up a Linux virtual machine (preferably something lightweight and without a DE, e.g. Arch Linux or Artix Linux) the same way as regular QEMU.

Note

If not using a systemd-based Linux distribution, additional setup for udev rules and service startup might be required.

iDevice Tool Setup

Note

This is done in the companion.

We will be using the 3rd party libimobiledevice tools. These act similar to Apple's but are open source and cross-platform.

The latest releases are heavily outdated, we must build the tools from source.

More details in each project's README.

Required projects to build from the repositories: idevicerestore libimobiledevice libimobiledevice-glue libirecovery libplist libtatsu libusbmuxd usbmuxd (not in any particular order).

Example build command:

PKG_CONFIG_PATHS=/usr/local/lib/pkgconfig/ ./autogen.sh && make -j$(nproc) && sudo make install

For idevicerestore, you must apply the following small patch for the restore to succeed:

idevicerestore.patch

Apply it like so:

git apply ../idevicerestore.patch

Transferring the IPSW and AP Ticket

Note

This is done from the host.

You can use a tool such as scp to transfer the IPSW into the companion VM. Here is one of the ways to do it:

Allow port forwarding from the guest to the host, i.e. -nic user,model=virtio-net-pci,hostfwd=tcp::32222-:22 in the QEMU command line.

This will forward the TCP port 22 from the guest to 32222 on the host.

Note

Depending on the Linux distribution, you may need to install and enable sshd, or even configure it. Consult the distribution's manual.

Afterwards, you can copy the IPSW and ticket into the VM like so:

scp iPhone11,8,iPhone12,1_14.0_18A5351d_Restore.ipsw scp://YOURUSER@localhost:32222/
scp root_ticket.der scp://YOURUSER@localhost:32222/