This is a library and command line tool to control port forwarding to jailbroken iOS devices.
Basically, it lets you do:
$ ssh root@localhost -p 2000and you get a shell to an iDevice connected over a USB wire.
The command line tool is called gandalf and it requires that
usbmuxd be running. If on OS X then you don't have to do anything,
if on Linux then you need to have the open source version of
usbmuxd. I recommend
compiling from source, versions on most package managers are old.
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, aka apt-get or whatever). NOTE if you are on Ubuntu, then you need to do:
$ add-apt-repository ppa:avsm/ppa
$ apt-get update
$ apt-get install ocaml opamIt is important that your compiler is up to date, you can
check with opam switch, make sure its at least >= 4.02.0. Currently
gandalf works with versions between ["4.02.0", "4.03.0"). Once
ppx_core updates then I can update as well to let you use "4.03.0".
then
$ opam install usbmuxThis will install the command line tool gandalf and an OCaml
library.
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.
-
See with realtime updates what devices are connected
$ gandalf
This will start up
gandalfin listen mode, that is it will print out whenever a device connects or disconnects. -
Start with a mapping file such that # start comments and consists of an array of json objects with these fields, note that name can be null and is just a nickname for this tunnel, other fields are required.
# This is a comment [{"udid":"9cdfac9f74c5e18a6eff3611c0927df5cf4f2eca", "name":"i11", "forwarding": [{"local_port":2000, "device_port":22}, {"local_port":3000, "device_port":1122}] }]$ 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.
-
To see a pretty JSON representation of devices and their ports that are currently connected, do:
$ gandalf -s
-
To reload the
gandalfwith 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.
-
To cleanly exit
gandalf, do: NOTE This might require super user permissions.$ gandalf -e
Check out the man page, accessible with:
$ gandalf --helpor
$ man gandalfSimple invocation:
$ sudo `which gandalf` --mappings etc/mapping --daemonize --verbose-
If you are running this on Linux, then you might get issues with
usbmuxdhaving issues when more than around 7 devices are plugged in. This is because multiple threads are trying to call variouslibxml2freeing functions. I have a forked version oflibplistthatusbmuxduses, sans the memory freeing calls. Its available here. Compile and install that, then compile and installusbmuxdfrom source. This will leak memory but its not that much at all and I believe it to be a fixed amount. -
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
For reference, this project is currently in use given these two issues and works fine with > 20 iPhones.
- Much appreciation to MixRank for green lighting this project
- Ivg, Edwin and others on #OCaml
- Starting point ideas from irelay, an npm package.
Future plans include writing C bindings to libusbmuxd itself, thereby
eliminating the dependency on usbmuxd.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent