SSH Over USB: Difference between revisions

From iPhone Development Wiki
m (→‎Installation: Use terminal template)
 
(29 intermediate revisions by 11 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 ===


* 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)].
<tabber>
* on Linux usbmux is provided by libimobiledevice, install it using your distro's package manager.
|-|macOS=
* If you're on Windows, install iTunes
With Homebrew:{{Terminal|macos|brew install libusbmuxd}}
* Unzip to a directory of choice.
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.


** Windows: Run <code>path/to/itunnel_mux.exe --iport 22 --lport 2222</code>
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.
** OS X: Run <code>sudo path/to/itnl --iport 22 --lport 2222</code>
|-|Linux=
** Linux: <code>iproxy 2222 22</code>
{{#tag:tabber|
Ubuntu=


Connect to localhost as you would over wifi.
<pre>
sudo apt-get install usbmuxd
</pre>


==== Making itunnel mux run automatically in the background on OS X ====
{{!}}-{{!}}
* Save the unzipped folder (containing both itnl and libmd.dylib) somewhere (eg. <code>/Library/itunnel</code>)
* Create the file <code>/Library/LaunchDaemons/com.usbmux.itunnel.plist</code> with the contents:
<pre>
<?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.itunnel</string>
<key>ProgramArguments</key>
<array>
<string>/path/to/itnl</string>
<string>--iport</string>
<string>22</string>
<string>--lport</string>
<string>2222</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>
</dict>
</plist>
</pre>


* (replacing /path/to/ with the path to where you have itnl stored, eg. <code>/Library/itunnel/</code>)
Debian=
* run <code>sudo launchctl load /Library/LaunchDaemons/com.usbmux.itunnel.plist</code>
<pre>
* You now don't have to run the itunnel binary every time you want to SSH over USB as the itunnel software is always running in the background
sudo apt-get install usbmuxd
</pre>


=== Using python ===
{{!}}-{{!}}
openSUSE=


Tested on OS X and Windows.
<pre>
sudo zypper install usbmuxd
</pre>


You will need to have Python installed on your system.
}}
</tabber>


* 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].)
=== Usage ===
* 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
<tabber>
|-|macOS/Linux=


The -t switch tells tcprelay to run threaded and allow more than one ssh over the same port.
You can set up your ssh config to connect automatically via inetcat


See ./tcprelay.py --help for further options.
In your ~/.ssh/config file: 
<pre>
Host my-iphone
    ProxyCommand inetcat 22 <my-phone-uuid>
    User root
    StrictHostKeyChecking no
    UserKnownHostsFile /dev/null
</pre>


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


=== Using gandalf ===
Then, you can simply connect via


Tested on OS X and Linux, each with up to 29 devices connected at the same time. The advantage of using
<code>ssh my-iphone</code>
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.


* Installation
Alternatively, without editing your ssh config, you can connect directly via:
You need to have opam installed, it is OCaml's package manager.


On OS X you can do:
<code>
ssh -oProxyCommand="inetcat 22" root@localhost
</code>


<pre>
(The default password will be `alpine`)
$ brew install opam
</pre>


(If on Linux, then get opam via your package manager, details available https://opam.ocaml.org/doc/Install.html,
|-|Windows=
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
Assuming you've added the <code>libimobiledevice</code> folder you extracted earlier to your PATH:


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


This will install the command line tool gandalf and an OCaml
Where <code>2222</code> is our "local" port, and <code>22</code> is the port on the device we want to forward.
library.


* gandalf usage.
We can then connect to the device by running:


The following are a series of usages of gandalf, all short form
<code>ssh root@localhost -p 2222</code>
arguments have long-forms as well and -v can be added at any time.


1) See with realtime updates what devices are connected
You may need to install ssh via Windows to connect to your device.


<pre>
If you have multiple devices connected, it may be useful to run multiple instances, specifying UDIDs and ports like so:
$ gandalf
</pre>
This will start up gandalf in listen mode, that is it will print
out whenever a device connects or disconnects.


2) Start with a mapping file which is of the form
<source lang="bash">
  <udid>:<local_port>:<device_port>. The ~#~ character starts comments
iproxy 2222 22 abcdef0123456789abcdef1234567890abcdef12 & \
So an example mapping file would be:
iproxy 2223 22 9876543210fedcba9876543210fedcba98765432
</source>


<pre>
</tabber>
# 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:  
== Integration with THEOS ==
Export the following variables in your shell in order to deploy builds to the connected device:


<pre>
<code>export THEOS_DEVICE_IP=localhost
$ 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
export THEOS_DEVICE_PORT=2222
make a pid file under /var/run.
</code>


3) To see a pretty JSON representation of devices and their ports that are currently connected, do:
== SSH without password ==
 
Run the following commands one time and you will not be asked to type your password again.
<pre>
$ gandalf -s
</pre>


4) To reload gandalf with a new set of mappings, do:
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.


<pre>
Then run the following command:
$ gandalf -r
<code>ssh-copy-id root@DEVICE_IP</code>
</pre>


This will cancel all running threads and reload from the original
On OS X, ssh-copy-id will need to be installed with <code>brew install ssh-copy-id</code>.
mappings file, so make your changes there.


5) To cleanly exit gandalf, do: *NOTE* This might require super user permissions.
== Alternatives to usbmuxd ==
<pre>
$ gandalf -e
</pre>


Check out the man page, accessible with:
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.
<pre>
$ gandalf --help
</pre>


or  
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.


<pre>
=== Using gandalf ===
$ 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 191: Line 133:
* Assign ports as you see fit.
* Assign ports as you see fit.


== 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
[[Category:Getting Started]]
</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>

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"