SSH Over USB: Difference between revisions

From iPhone Development Wiki
m (→‎Making iproxy run automatically in the background on OS X: Specific device targetting per UDID.)
m (→‎Installation: Use terminal template)
 
(17 intermediate revisions by 6 users not shown)
Line 3: Line 3:
== SSH over USB using usbmuxd ==
== 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.  
Utilizing <code>inetcat</code>, a component of <code>[[usbmuxd]]</code>, is the preferred (and likely only actively maintained) method of connecting to SSH via USB across iDevices.


=== Using binary ===
=== Installation ===


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.
<tabber>
|-|macOS=
With Homebrew:{{Terminal|macos|brew install libusbmuxd}}
With Macports:{{Terminal|macos|sudo port install libusbmuxd}}
|-|Windows=
A compiled version of libimobiledevice+usbmuxd is available [https://github.com/L1ghtmann/libimobiledevice/releases/latest here]. Download the .tar.xz file and extract it using [https://www.7-zip.org/ 7-zip] or a similar program.


On OS X and Linux, install libimobiledevice from your package manager.
You can add this extracted folder to the path by following the walkthrough [https://stackoverflow.com/a/44272417 here]. This will put the iproxy bin on your path.
|-|Linux=
{{#tag:tabber|
Ubuntu=


Then:
<pre>
sudo apt-get install usbmuxd
</pre>


* 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.
Debian=
<pre>
sudo apt-get install usbmuxd
</pre>


If you have multiple devices connected, it may be useful to run multiple instances, specifying UDIDs and ports like so:
{{!}}-{{!}}
openSUSE=


<source lang="bash">
<pre>
iproxy 2222 22 abcdef0123456789abcdef1234567890abcdef12 & \
sudo zypper install usbmuxd
iproxy 2223 22 9876543210fedcba9876543210fedcba98765432
</pre>
</source>


==== Making iproxy run automatically in the background on OS X ====
}}
</tabber>


* Install it with Homebrew (<code>brew install libimobiledevice</code>).
=== Usage ===
* 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>.
<tabber>
* 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.
|-|macOS/Linux=


If you have several devices you can create a daemon with a specific port for each one.
You can set up your ssh config to connect automatically via inetcat
* 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. <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>
<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 ===
In your ~/.ssh/config file: 
<pre>
Host my-iphone
    ProxyCommand inetcat 22 <my-phone-uuid>
    User root
    StrictHostKeyChecking no
    UserKnownHostsFile /dev/null
</pre>


Tested on OS X and Windows.
(You don't need to specify uuid if you only have one phone connected)


You will need to have Python installed on your system.
Then, you can simply connect via


* 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].)
<code>ssh my-iphone</code>
* 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
Alternatively, without editing your ssh config, you can connect directly via:


The -t switch tells tcprelay to run threaded and allow more than one ssh over the same port.
<code>
 
ssh -oProxyCommand="inetcat 22" root@localhost
See ./tcprelay.py --help for further options.
</code>
 
 
=== Using gandalf ===


Tested on OS X and Linux, each with up to 29 devices connected at the same time. The advantage of using
(The default password will be `alpine`)
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
|-|Windows=
You need to have opam installed, it is OCaml's package manager.


On OS X you can do:
Assuming you've added the <code>libimobiledevice</code> folder you extracted earlier to your PATH:


<pre>
<pre>
$ brew install opam
iproxy 2222:22
</pre>
</pre>


(If on Linux, then get opam via your package manager, details available https://opam.ocaml.org/doc/Install.html,
Where <code>2222</code> is our "local" port, and <code>22</code> is the port on the device we want to forward.
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
We can then connect to the device by running:


<pre>
<code>ssh root@localhost -p 2222</code>
$ opam install usbmux
</pre>


This will install the command line tool gandalf and an OCaml
You may need to install ssh via Windows to connect to your device.
library.


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


The following are a series of usages of gandalf, all short form
<source lang="bash">
arguments have long-forms as well and -v can be added at any time.
iproxy 2222 22 abcdef0123456789abcdef1234567890abcdef12 & \
iproxy 2223 22 9876543210fedcba9876543210fedcba98765432
</source>


1) See with realtime updates what devices are connected
</tabber>


<pre>
== Integration with THEOS ==
$ gandalf
Export the following variables in your shell in order to deploy builds to the connected device:
</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
<code>export THEOS_DEVICE_IP=localhost
  <udid>:<local_port>:<device_port>. The # character starts comments
So an example mapping file would be:


<pre>
export THEOS_DEVICE_PORT=2222
# the phone1 udid, local port 2000, phone's port 22 aka ssh
</code>
123456dfg213423453456123dfg:2000:22
# phone 2, same deal but note different local port
frgfg2345345123jifgidfug123:2001:22
</pre>


and the gandalf invocation is:
== SSH without password ==
Run the following commands one time and you will not be asked to type your password again.


<pre>
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.
$ 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
Then run the following command:
make a pid file under /var/run.
<code>ssh-copy-id root@DEVICE_IP</code>


3) To see a pretty JSON representation of devices and their ports that are currently connected, do:
On OS X, ssh-copy-id will need to be installed with <code>brew install ssh-copy-id</code>.
 
<pre>
$ gandalf -s
</pre>


4) To reload gandalf with a new set of mappings, do:
== Alternatives to usbmuxd ==


<pre>
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 usbmuxd, one may find it easier to just use usbmuxd itself.
$ gandalf -r
</pre>


This will cancel all running threads and reload from the original
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.  
mappings file, so make your changes there.


5) To cleanly exit gandalf, do: *NOTE* This might require super user permissions.
=== Using gandalf ===
<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
Gandalf is a tool written in OCaml for connecting to a large amount of devices via SSH over USB.


1) If you are running this on Linux, then you might get issues with
Instructions on installation and usage can be viewed on the [[Gandalf]] page, or on the project's [https://github.com/onlinemediagroup/ocaml-usbmux README]
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
=== SSH over USB using the iFunBox GUI (Windows only) ===
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.
This feature only exists in the '''Windows build''' of iFunBox.
Line 223: Line 133:
* Assign ports as you see fit.
* Assign ports as you see fit.


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


[https://code.google.com/archive/p/iphonetunnel-mac/downloads Google Code Archive]
[[Category:Getting Started]]
 
[https://www.dropbox.com/s/mz4asmq8zc87hvh/iPhoneTunnel.app.zip?dl=0 DropBox Mirrori]
 
# 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 command one time and you will not be asked to type your password again.
 
<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>.

Latest revision as of 05:11, 7 October 2023

Languages: English • français • ไทย

SSH over USB using usbmuxd

Utilizing inetcat, 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

You can set up your ssh config to connect automatically via inetcat

In your ~/.ssh/config file: 

Host my-iphone
    ProxyCommand inetcat 22 <my-phone-uuid>
    User root
    StrictHostKeyChecking no
    UserKnownHostsFile /dev/null

(You don't need to specify uuid if you only have one phone connected)

Then, you can simply connect via

ssh my-iphone

Alternatively, without editing your ssh config, you can connect directly via:

ssh -oProxyCommand="inetcat 22" root@localhost

(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

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 usbmuxd

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 usbmuxd, one may find it easier to just use usbmuxd 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.
Retrieved from "https://iphonedev.wiki/index.php?title=SSH_Over_USB&oldid=6135"