SSH Over USB: Difference between revisions

From iPhone Development Wiki
m (updating language option)
m (Reverted edits by Silent.ashes (talk) to last revision by PoomSmart)
Tag: Rollback
(37 intermediate revisions by 17 users not shown)
Line 3: Line 3:
== SSH over USB using usbmuxd ==
== SSH over USB using usbmuxd ==


=== With Python ===
You can either download a binary and run that or use a python script. The python script is a lot slower than the binary version. On Linux the python method is mostly deprecated, use the binary version provided by libimobiledevice. There is also a newer solution called gandalf.
 
=== Using binary ===
 
On Windows, ensure iTunes is installed, then download itunnel_mux_rev71.zip from [https://code.google.com/archive/p/iphonetunnel-usbmuxconnectbyport/downloads Google Code]. Unzip to a directory of choice.
 
On OS X and Linux, install [https://github.com/libimobiledevice/usbmuxd usbmuxd] from your package manager.
 
Then:
 
* Windows: Run <code>path/to/itunnel_mux.exe --iport 22 --lport 2222</code>
* OS X/Linux: <code>iproxy 2222 22</code>
 
Connect to <code>localhost -p 2222</code> as you would over wifi.
 
If you have multiple devices connected, it may be useful to run multiple instances, specifying UDIDs and ports like so:
 
<source lang="bash">
iproxy 2222 22 abcdef0123456789abcdef1234567890abcdef12 & \
iproxy 2223 22 9876543210fedcba9876543210fedcba98765432
</source>
 
==== Making iproxy run automatically in the background on OS X ====
 
* Install it with Homebrew (<code>brew install libimobiledevice</code>).
* Create the file <code>~/Library/LaunchAgents/com.usbmux.iproxy.plist</code> with the contents:
<source lang="xml">
<?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>
</source>
 
* Run <code>launchctl load ~/Library/LaunchAgents/com.usbmux.iproxy.plist</code>.
* 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 <code>~/Library/LaunchAgents/</code> but name it using the device UDID, name or an identifier of your choice (like <code>com.usbmux.iproxy.iPhone7,2.plist</code>).
* Replace <tt>UDID_HERE</tt> in the following snippet with the device UDID. The label should be unique and is best to match the filename you used.
 
<source lang="xml">
<?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>
</source>
* Run <code>launchctl load ~/Library/LaunchAgents/FILE_NAME_OF_YOUR_CHOICE</code>.
* 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.
 
=== Using Python ===


Tested on OS X and Windows.
Tested on OS X and Windows.
Line 9: Line 87:
You will need to have Python installed on your system.
You will need to have Python installed on your system.


* Get [http://marcansoft.com/blog/iphonelinux/usbmuxd/ usbmuxd] source package and unpack
* Get [http://marcansoft.com/blog/iphonelinux/usbmuxd/ usbmuxd] source package and unpack. (Or if the linked usbmuxd package doesn't work, try [http://cgit.sukimashita.com/libusbmuxd.git/ libusbmuxd].)
* Go into folder python-client
* Go into folder python-client
* chmod +x tcprelay.py
* <code>chmod +x tcprelay.py</code>
* Run ./tcprelay.py -t 22:2222
* Run <code>./tcprelay.py -t 22:2222</code>


Now you can log into your device via ssh mobile@localhost -p 2222
Now you can log into your device via <code>ssh mobile@localhost -p 2222</code>


The -t switch tells tcprelay to run threaded and allow more than one ssh over the same port.
The -t switch tells tcprelay to run threaded and allow more than one ssh over the same port.
Line 20: Line 98:
See ./tcprelay.py --help for further options.
See ./tcprelay.py --help for further options.


=== Without Python ===
=== Using gandalf ===


* Download the zip file from [https://code.google.com/p/iphonetunnel-usbmuxconnectbyport/downloads/detail?name=itnl_rev8.zip OS X] or [https://code.google.com/p/iphonetunnel-usbmuxconnectbyport/downloads/detail?name=itunnel_mux_rev71.zip Windows (32 bits)].
Tested on OS X and Linux, each with up to 29 devices connected at the same time. The advantage of using
* Unzip to a directory of choice.
gandalf is that it is written in a functional programming language, which practically means that it won't
* Run <code>path/to/itunnel_mux.exe --lport 22 --iport 22</code>
give you seg faults and it is actively maintained https://github.com/onlinemediagroup/ocaml-usbmux


Connect to localhost as you would over wifi.
* Installation
You need to have opam installed, it is OCaml's package manager.
 
On OS X you can do:
 
<pre>
$ brew install opam
</pre>
 
(If on Linux, then get opam via your package manager, details available https://opam.ocaml.org/doc/Install.html,
Ubuntu users please pay attention, need to use a ppa for opam).
It is important that your compiler is up to date, you can
check with opam switch, make sure its at least >= 4.02.0
 
then
 
<pre>
$ opam install usbmux
</pre>
 
This will install the command line tool gandalf and an OCaml
library.
 
* gandalf usage.
 
The following are a series of usages of gandalf, all short form
arguments have long-forms as well and -v can be added at any time.
 
1) See with realtime updates what devices are connected
 
<pre>
$ gandalf
</pre>
This will start up gandalf in listen mode, that is it will print
out whenever a device connects or disconnects and more crucially
it will print out the UDID of each device.
 
2) Start with a mapping file which is of the form
  <udid>:<local_port>:<device_port>. The # character starts comments
So an example mapping file would be:
 
<pre>
# the phone1 udid, local port 2000, phone's port 22 aka ssh
123456dfg213423453456123dfg:2000:22
# phone 2, same deal but note different local port
frgfg2345345123jifgidfug123:2001:22
</pre>
 
and the gandalf invocation is:
 
<pre>
$ gandalf -m mapping
</pre>
 
2.1) You can also daemonize gandalf with the -d flag. *NOTE*: You might need to end up doing that under sudo as gandalf needs to
make a pid file under /var/run.
 
3) To see a pretty JSON representation of devices and their ports that are currently connected, do:
 
<pre>
$ gandalf -s
</pre>
 
4) To reload gandalf with a new set of mappings, do:
 
<pre>
$ gandalf -r
</pre>
 
This will cancel all running threads and reload from the original
mappings file, so make your changes there.
 
5) To cleanly exit gandalf, do: *NOTE* This might require super user permissions.
<pre>
$ gandalf -e
</pre>
 
Check out the man page, accessible with:
<pre>
$ gandalf --help
</pre>
 
or
 
<pre>
$ man gandalf
</pre>
 
Simple invocation:
 
<pre>
$ sudo `which gandalf` --mappings etc/mapping --daemonize --verbose
</pre>
 
* Important Notes and Catches
 
1) If you are running this on Linux, then you might get issues with
usbmuxd having issues when more than around 7 devices are plugged
in. This is because multiple threads are trying to call various
libxml2 freeing functions. I have a forked version of libplist
that usbmuxd uses, sans the memory freeing calls. Its available
[https://github.com/onlinemediagroup/libplist here]. Compile and install that, then compile and install usbmuxd
from source. This will leak memory but its not that much at all and
I believe it to be a fixed amount.
 
2) Another issue you might have is USB3.0. The Linux kernel might crap
out on you after 13 devices. This is a combination of the kernel
not giving enough resources and the host controller on your
motherboard being crappy. The solution to this problem is to
disable USB3.0 in your BIOS. To verify that USB3.0 isn't working
check with lsusb


== SSH over USB using the iFunBox GUI (Windows only) ==
== SSH over USB using the iFunBox GUI (Windows only) ==
Line 35: Line 223:
* Click on "Quick Toolbox," then "USB Tunnel."
* Click on "Quick Toolbox," then "USB Tunnel."
* Assign ports as you see fit.
* Assign ports as you see fit.
== SSH over USB using iPhoneTunnel Menu Bar Application (macOS Intel only) ==
[https://code.google.com/archive/p/iphonetunnel-mac/downloads Google Code Archive]
[https://www.dropbox.com/s/mz4asmq8zc87hvh/iPhoneTunnel.app.zip?dl=0 DropBox Mirror]
# Turn Tunnel On
# Tools -> SSH
== Theos usage ==
Export the following variables in your shell in order to deploy builds to the connected device:
<code>export THEOS_DEVICE_IP=localhost
export THEOS_DEVICE_PORT=2222
</code>
== 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 <code>ssh-keygen</code> if you have not created one. A passphrase isn’t required but still recommended. You can use <code>ssh-agent</code> [https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/ as described here] to keep the passphrase in memory and not be prompted for it constantly.
Then run the following command:
<code>ssh-copy-id root@DEVICE_IP</code>
On OS X, ssh-copy-id will need to be installed with <code>brew install ssh-copy-id</code>.

Revision as of 00:42, 10 February 2023

Languages: English • françaisไทย

SSH over USB using usbmuxd

You can either download a binary and run that or use a python script. The python script is a lot slower than the binary version. On Linux the python method is mostly deprecated, use the binary version provided by libimobiledevice. There is also a newer solution called gandalf.

Using binary

On Windows, ensure iTunes is installed, then download itunnel_mux_rev71.zip from Google Code. Unzip to a directory of choice.

On OS X and Linux, install usbmuxd from your package manager.

Then:

  • Windows: Run path/to/itunnel_mux.exe --iport 22 --lport 2222
  • OS X/Linux: iproxy 2222 22

Connect to localhost -p 2222 as you would over wifi.

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.

Using Python

Tested on OS X and Windows.

You will need to have Python installed on your system.

  • Get usbmuxd source package and unpack. (Or if the linked usbmuxd package doesn't work, try libusbmuxd.)
  • Go into folder python-client
  • chmod +x tcprelay.py
  • Run ./tcprelay.py -t 22:2222

Now you can log into your device via ssh mobile@localhost -p 2222

The -t switch tells tcprelay to run threaded and allow more than one ssh over the same port.

See ./tcprelay.py --help for further options.

Using gandalf

Tested on OS X and Linux, each with up to 29 devices connected at the same time. The advantage of using gandalf is that it is written in a functional programming language, which practically means that it won't give you seg faults and it is actively maintained https://github.com/onlinemediagroup/ocaml-usbmux

  • Installation

You need to have opam installed, it is OCaml's package manager.

On OS X you can do:

$ brew install opam

(If on Linux, then get opam via your package manager, details available https://opam.ocaml.org/doc/Install.html, Ubuntu users please pay attention, need to use a ppa for opam). It is important that your compiler is up to date, you can check with opam switch, make sure its at least >= 4.02.0

then

$ opam install usbmux

This will install the command line tool gandalf and an OCaml library.

  • gandalf usage.

The following are a series of usages of gandalf, all short form arguments have long-forms as well and -v can be added at any time.

1) See with realtime updates what devices are connected

$ gandalf

This will start up gandalf in listen mode, that is it will print out whenever a device connects or disconnects and more crucially it will print out the UDID of each device.

2) Start with a mapping file which is of the form

  <udid>:<local_port>:<device_port>. The # character starts comments

So an example mapping file would be:

# the phone1 udid, local port 2000, phone's port 22 aka ssh
123456dfg213423453456123dfg:2000:22
# phone 2, same deal but note different local port 
frgfg2345345123jifgidfug123:2001:22

and the gandalf invocation is:

$ gandalf -m mapping

2.1) You can also daemonize gandalf with the -d flag. *NOTE*: You might need to end up doing that under sudo as gandalf needs to make a pid file under /var/run.

3) To see a pretty JSON representation of devices and their ports that are currently connected, do:

$ gandalf -s

4) To reload gandalf with a new set of mappings, do:

$ gandalf -r

This will cancel all running threads and reload from the original mappings file, so make your changes there.

5) To cleanly exit gandalf, do: *NOTE* This might require super user permissions.

$ gandalf -e

Check out the man page, accessible with:

$ gandalf --help

or

$ man gandalf

Simple invocation:

$ sudo `which gandalf` --mappings etc/mapping --daemonize --verbose
  • Important Notes and Catches

1) If you are running this on Linux, then you might get issues with usbmuxd having issues when more than around 7 devices are plugged in. This is because multiple threads are trying to call various libxml2 freeing functions. I have a forked version of libplist that usbmuxd uses, sans the memory freeing calls. Its available here. Compile and install that, then compile and install usbmuxd from source. This will leak memory but its not that much at all and I believe it to be a fixed amount.

2) Another issue you might have is USB3.0. The Linux kernel might crap out on you after 13 devices. This is a combination of the kernel not giving enough resources and the host controller on your motherboard being crappy. The solution to this problem is to disable USB3.0 in your BIOS. To verify that USB3.0 isn't working check with lsusb

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.

SSH over USB using iPhoneTunnel Menu Bar Application (macOS Intel only)

Google Code Archive

DropBox Mirror

  1. Turn Tunnel On
  2. Tools -> SSH

Theos usage

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.