SSH Over USB

Languages: English • français • ไทย

SSH over USB using usbmuxd

Utilizing iproxy, a component of usbmuxd, is the preferred (and likely only actively maintained) method of connecting to SSH via USB across iDevices.

Installation

With Homebrew:

brew install libusbmuxd

With Macports:

sudo port install libusbmuxd

A compiled version of libimobiledevice+usbmuxd is available here. Download the .tar.xz file and extract it using 7-zip or a similar program. You can add this extracted folder to the path by following the walkthrough here. This will put the iproxy bin on your path.

 sudo apt-get install usbmuxd
 

sudo apt-get install usbmuxd

 

sudo zypper install usbmuxd

 

Usage

Official distributions of usbmuxd will have added the iproxy tool to your path.

While the iproxy command can do several things (detailed on the usbmuxd page), here our usage is very basic:

iproxy 2222:22

Where 2222 is our "local" port, and 22 is the port on the device we want to forward.

We can then connect to the device by running:

ssh root@localhost -p 2222

(The default password will be `alpine`)

Assuming you've added the libimobiledevice folder you extracted earlier to your PATH:

iproxy 2222:22

Where 2222 is our "local" port, and 22 is the port on the device we want to forward.

We can then connect to the device by running:

ssh root@localhost -p 2222

You may need to install ssh via Windows to connect to your device.

If you have multiple devices connected, it may be useful to run multiple instances, specifying UDIDs and ports like so:

iproxy 2222 22 abcdef0123456789abcdef1234567890abcdef12 & \
iproxy 2223 22 9876543210fedcba9876543210fedcba98765432

Making iproxy run automatically in the background on OS X

• Install it with Homebrew (brew install libimobiledevice).
• Create the file ~/Library/LaunchAgents/com.usbmux.iproxy.plist with the contents:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>Label</key>
	<string>com.usbmux.iproxy</string>
	<key>ProgramArguments</key>
	<array>
		<string>/usr/local/bin/iproxy</string>
		<string>2222</string>
		<string>22</string>
	</array>
	<key>RunAtLoad</key>
	<true/>
	<key>KeepAlive</key>
	<true/>
</dict>
</plist>

• Run launchctl load ~/Library/LaunchAgents/com.usbmux.iproxy.plist.
• You now don't have to run the iproxy binary every time you want to SSH over USB as the iproxy software is always running in the background.

If you have several devices you can create a daemon with a specific port for each one.

• Create a file in ~/Library/LaunchAgents/ but name it using the device UDID, name or an identifier of your choice (like com.usbmux.iproxy.iPhone7,2.plist).
• Replace UDID_HERE in the following snippet with the device UDID. The label should be unique and is best to match the filename you used.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>Label</key>
	<string>com.usbmux.iproxy.iPhone7,2</string>
	<key>ProgramArguments</key>
	<array>
		<string>/usr/local/bin/iproxy</string>
		<string>2222</string>
		<string>22</string>
		<string>UDID_HERE</string>
	</array>
	<key>RunAtLoad</key>
	<true/>
	<key>KeepAlive</key>
	<true/>
</dict>
</plist>

• Run launchctl load ~/Library/LaunchAgents/FILE_NAME_OF_YOUR_CHOICE.
• You now don't have to run the iproxy binary every time you want to SSH over USB as the iproxy software is always running in the background.

Integration with THEOS

Export the following variables in your shell in order to deploy builds to the connected device:

export THEOS_DEVICE_IP=localhost

export THEOS_DEVICE_PORT=2222

SSH without password

Run the following commands one time and you will not be asked to type your password again.

You must create an SSH key with ssh-keygen if you have not created one. A passphrase isn’t required but still recommended. You can use ssh-agent as described here to keep the passphrase in memory and not be prompted for it constantly.

Then run the following command: ssh-copy-id root@DEVICE_IP

On OS X, ssh-copy-id will need to be installed with brew install ssh-copy-id.

Alternatives to iproxy

There are several other methods of connecting to devices, however the ones that still work typically just wrap usbmuxd, and given the simplicity of installation and usage of iproxy, one may find it easier to just use iproxy itself.

However, for a variety of reasons (automation, CI, more convenient integration into another project, or an aversion to CLI tools), one may want to use other tools.

Using gandalf

Gandalf is a tool written in OCaml for connecting to a large amount of devices via SSH over USB.

Instructions on installation and usage can be viewed on the Gandalf page, or on the project's README

SSH over USB using the iFunBox GUI (Windows only)

This feature only exists in the Windows build of iFunBox.

• Get the latest Windows build of iFunBox and install it.
• Click on "Quick Toolbox," then "USB Tunnel."
• Assign ports as you see fit.