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, optionally (defaults to unix) specified in the -M flag:
  • usb-conn-type: unix (default), ipv4, or ipv6. UNIX sockets are not supported on Windows.
  • usb-conn-addr: File path for unix, IP address for ipv4 and ipv6.
  • usb-conn-port: Server port for use with ipv4 and ipv6 only.
  • for example: -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 (defaults to unix), -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

Additional setup for udev rules, service startup and an additional user may be required, especially if not on a systemd-based distribution.

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_PATH=/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/