idevicepair

Pair a device with the host

$ idevicepair pair

$ idevicepair list

idevicepair [OPTIONS] COMMAND

pair
    Establishes a new pairing record with a connected device. Requires user interaction on the iDevice to 'Trust This Computer'.

unpair
    Removes the pairing record for a specified device. Can be used with the -u option to target a specific UDID.

validate
    Checks if an existing pairing record for a device is still valid and trusted.

list
    Lists all known paired devices by their UDID and name.

unpair-all
    Removes all known pairing records from the host system.

-u, --udid
    Specifies the 40-character Unique Device Identifier (UDID) of the target iDevice. Useful when multiple devices are connected or for specific actions.

-d, --debug
    Enables verbose debug output, useful for troubleshooting pairing issues.

-x, --xml
    Outputs pairing information or results in XML format, suitable for programmatic parsing.

-h, --help
    Displays a brief help message and usage information.

-v, --version
    Shows the version information of the idevicepair utility.

idevicepair is a crucial command-line utility from the libimobiledevice project, designed to establish and manage trust relationships (pairing records) between a Linux host and an Apple iOS device (iPhone, iPad, iPod Touch). This pairing process involves a secure key exchange, which is fundamental for other libimobiledevice tools like ideviceinstaller, idevicescreenshot, or ifuse to communicate effectively with the connected device.

It handles the secure negotiation and storage of pairing certificates, allowing for persistent and authorized access. Without a successful pairing, most advanced interactions with an iOS device from a Linux system are not possible. It's an essential first step for developers, power users, or anyone looking to integrate their iDevice with a Linux environment.

• usbmuxd Daemon: idevicepair relies on the usbmuxd (USB Multiplex Daemon) service running in the background. If usbmuxd is not running or accessible, communication with the iDevice will fail.
• Device Interaction: During the 'pair' command, the iDevice screen must be unlocked, and the user must manually tap 'Trust' on the 'Trust This Computer?' prompt for the pairing to succeed.
• Firewall/Permissions: Ensure no firewall rules block communication over the necessary USB ports or local sockets used by usbmuxd. Proper USB device permissions are also crucial.
• Connectivity Issues: Sometimes, physical reconnection of the USB cable or restarting the iDevice might be necessary if pairing consistently fails.
• iOS Version Dependency: Apple frequently updates its security protocols with new iOS versions, which may temporarily break compatibility with libimobiledevice tools until updates are released.

When executing idevicepair pair, your iOS device will display a 'Trust This Computer?' prompt. It is absolutely essential to tap 'Trust' on your device for the pairing process to complete successfully. Failing to do so will result in a pairing error on the host.

The UDID is a unique 40-character alphanumeric string that identifies each iOS device. You can find your device's UDID using the idevice_id -l command. Specifying the UDID with the -u option is vital when you have multiple devices connected or want to ensure you're performing an action on a specific device.

Once a device is successfully paired, the host stores a pairing record, typically in ~/.config/libimobiledevice/ or /var/lib/lockdown/. This record allows subsequent libimobiledevice commands to communicate with the device without requiring re-pairing, as long as the record remains valid on both the host and the device. These records are deleted by the unpair or unpair-all commands.

idevicepair is a core component of the libimobiledevice project, an open-source initiative that began around 2007 to enable communication with Apple's iDevices on Linux and other non-Apple platforms. Its development has closely tracked the evolution of iOS, adapting to Apple's changes in USB communication protocols and security mechanisms over the years. It has been instrumental in providing a stable and reliable method for developers and users to interact with iOS devices, filling a critical gap left by Apple's lack of official Linux support.

usbmuxd(8), idevice_id(1), ideviceinfo(1), ideviceinstaller(1), ifuse(1)