From iPhone Development Wiki

Tested on OS X and Linux, each with up to 29 devices connected at the same time.

View on GitHub

  • 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, 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


$ 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
# phone 2, same deal but note different local port 

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


$ 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. There is a forked version of libplist that usbmuxd uses, sans the memory freeing calls. It is available at here. Compile and install that, then compile and install usbmuxd from source. This will leak memory but it is 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