LinuxCommandLibrary

iproxy

Tunnel connections to iOS devices over USB

TLDR

Bind a local TCP port and forward it to a port on the connected USB device

$ iproxy [local_port]:[device_port]
copy

Bind multiple local TCP ports and forward them to the respective ports on the connected USB device
$ iproxy [local_port1]:[device_port1] [local_port2]:[device_port2]
copy

Bind a local port and forward it to a specific device by UDID
$ iproxy --udid [device_udid] [local_port]:[device_port]
copy

Bind a local port and forward it to a network-connected device with WiFi sync enabled
$ iproxy --network [local_port]:[device_port]
copy

SYNOPSIS

iproxy [OPTIONS] LOCAL_PORT:DEVICE_PORT [LOCAL_PORT:DEVICE_PORT ...]

PARAMETERS

--udid UDID, -u UDID
    Connects to the iOS device with the specified UDID. This is essential when multiple iOS devices are connected to the host machine, ensuring the forwarding targets the correct device.

--listen IP, -l IP
    Specifies the local IP address on which iproxy should listen for incoming connections. By default, it listens on 127.0.0.1 (localhost), making the forwarded port accessible only from the host machine.

--help, -h
    Displays a brief help message with command usage and available options.

--version, -v
    Prints the version information of the iproxy utility.

--debug, -d
    Enables verbose debug output, which can be helpful for troubleshooting connection issues or understanding the proxy's activity.

DESCRIPTION

iproxy is a utility from the libimobiledevice suite, designed to facilitate communication with Apple iOS devices (iPhones, iPods, iPads) over USB. Its primary function is to create a TCP port forwarding bridge between your host computer and a connected iOS device. This means you can establish a connection to a specific port on the iOS device (e.g., a service running on it) by connecting to a designated local port on your computer.

This is particularly useful for developers, system administrators, or users interacting with jailbroken devices to access services like SSH, debug applications, or manage device filesystems via network protocols, even when the device doesn't have an IP address accessible from the network directly, relying solely on the USB connection. It acts as a lightweight proxy, ensuring that data flowing to the local port is seamlessly relayed to the corresponding port on the iOS device.

CAVEATS

  • Requires libimobiledevice utilities to be installed.
  • The iOS device must be connected via USB and recognized by the system.
  • For services on the iOS device, ensure the service is running and listening on the specified DEVICE_PORT. For instance, SSH requires a daemon like OpenSSH to be installed and running on a jailbroken device.
  • Firewall rules on the host machine might need adjustment if you're attempting to access the local port from another machine on the network (and if --listen 0.0.0.0 is used).

COMMON USE CASES

  • SSH Access: Often used to forward local port 2222 to device port 22 (the standard SSH port) on a jailbroken iOS device, enabling secure shell access over USB.
  • Debugging Applications: Developers can use it to connect to services or debugging ports exposed by their applications running on the device.
  • Network Tooling: Facilitates the use of standard network tools (like nmap, curl) against services running on the iOS device.

MULTIPLE PORT FORWARDS

iproxy supports forwarding multiple local-to-device port pairs simultaneously in a single command, making it versatile for complex setups. For example: iproxy 2222:22 8080:80.

HISTORY

iproxy is a core component of the libimobiledevice project, an open-source initiative providing libraries and tools for communication with Apple devices running iOS, iPadOS, and tvOS. The project began around 2007, aiming to provide a cross-platform (Linux, macOS, Windows) alternative to Apple's proprietary iTunes and Xcode tools for interacting with iOS devices. iproxy specifically addresses the need for network access to device services over USB, a common requirement for developers and advanced users. Its development has mirrored the evolution of iOS, adapting to new device models and iOS versions to maintain compatibility and functionality.

SEE ALSO

Copied to clipboard