diff options
| -rw-r--r-- | README.md | 151 |
1 files changed, 112 insertions, 39 deletions
@@ -1,67 +1,140 @@ # libusbmuxd -## About +*A client library for applications to handle usbmux protocol connections with iOS devices* -A client library to multiplex connections from and to iOS devices by connecting -to a socket provided by a usbmuxd daemon. +## Features -## Requirements +This project is a client library to multiplex connections from and to iOS +devices alongside command-line utilities. -Development Packages of: -* libplist +It is primarily used by applications which use the [libimobiledevice](https://github.com/libimobiledevice/) +library to communicate with services running on iOS devices. -Software: -* usbmuxd (Windows and Mac OS X can use the one provided by iTunes) -* make -* autoheader -* automake -* autoconf -* libtool -* pkg-config -* gcc or clang +The library does not establish a direct connection with a device but requires +connecting to a socket provided by the usbmuxd daemon. -Optional: -* inotify (Linux only) +The usbmuxd daemon is running upon installing iTunes on Windows and Mac OS X. -## Installation +The [libimobiledevice project](https://github.com/libimobiledevice/) provides an open-source reimplementation of +the [usbmuxd daemon](https://github.com/libimobiledevice/usbmuxd.git/) to use on Linux or as an alternative to communicate with +iOS devices without the need to install iTunes. -To compile run: -```bash +- **Protocol:** Provides an interface to handle the usbmux protocol +- **Port Proxy:** Provides the `iproxy` utility to proxy ports to the device +- **Netcat:** Provides the `inetcat` utility to expose a raw connection to the device +- **Cross-Platform:** Tested on Linux, macOS, Windows and Android platforms +- **Flexible:** Allows using the open-source or proprietary usbmuxd daemon + +Furthermore the Linux build optionally provides support using inotify if +available. + +## Installation / Getting started + +### Debian / Ubuntu Linux + +First install all required dependencies and build tools: +```shell +sudo apt-get install \ + build-essential \ + checkinstall \ + git \ + autoconf \ + automake \ + libtool-bin \ + libplist-dev +``` + +Then clone the actual project repository: +```shell +git clone https://github.com/libimobiledevice/libusbmuxd.git +cd libusbmuxd +``` + +Now you can build and install it: +```shell ./autogen.sh make sudo make install ``` -If dependent packages cannot be found when running autogen.sh (or configure) -make sure that `pkg-config` is installed and set the `PKG_CONFIG_PATH` environment -variable if required. It can be passed directly like this: +## Usage + +### iproxy -```bash -PKG_CONFIG_PATH=/usr/local/lib/pkgconfig ./autogen.sh +This utility allows binding local TCP ports so that a connection to one (or +more) of the local ports will be forwarded to the specified port (or ports) on +a usbmux device. + +Bind local TCP port 2222 and forward to port 22 of the first device connected +via USB: +```shell +iproxy 2222:22 ``` -If you require a custom prefix or other option being passed to `./configure` -you can pass them directly to `./autogen.sh` like this: -```bash -./autogen.sh --prefix=/opt/local --without-cython -make -sudo make install +This would allow using ssh with `localhost:2222` to connect to the sshd daemon +on the device. Please mind that this is just an example and the sshd daemon is +only available for jailbroken devices that actually have it installed. + +Please consult the usage information or manual page for a full documentation of +available command line options: +```shell +iproxy --help +man iproxy ``` -## Who/What/Where? +### inetcat + +This utility is a simple netcat-like tool that allows opening a read/write +interface to a TCP port on a usbmux device and expose it via STDIN/STDOUT. -* Home: https://libimobiledevice.org/ -* Code: `git clone https://git.libimobiledevice.org/libusbmuxd.git` -* Code (Mirror): `git clone https://github.com/libimobiledevice/libusbmuxd.git` -* Tickets: https://github.com/libimobiledevice/libusbmuxd/issues +Use ssh ProxyCommand to connect to a jailbroken iOS device via SSH: +```shell +ssh -oProxyCommand="inetcat 22" root@localhost +``` + +Please consult the usage information or manual page for a full documentation of +available command line options: +```shell +inetcat --help +man inetcat +``` + +### Environment + +The environment variable `USBMUXD_SOCKET_ADDRESS` allows to change the location +of the usbmuxd socket away from the local default one. + +An example of using an utility from the libimobiledevice project with an usbmuxd +socket exposed on a port of a remote host: +```shell +export USBMUXD_SOCKET_ADDRESS=192.168.179.1:27015 +ideviceinfo +``` + +This sets the usbmuxd socket address to `192.168.179.1:27015` for applications +that use the libusbmuxd library. + +## Links + +* Homepage: https://libimobiledevice.org/ +* Repository: https://git.libimobiledevice.org/libusbmuxd.git +* Repository (Mirror): https://github.com/libimobiledevice/libusbmuxd.git +* Issue Tracker: https://github.com/libimobiledevice/libusbmuxd/issues * Mailing List: https://lists.libimobiledevice.org/mailman/listinfo/libimobiledevice-devel * Twitter: https://twitter.com/libimobiledev +## License + +This library is licensed under the [GNU Lesser General Public License v2.1](https://www.gnu.org/licenses/lgpl-2.1.en.html), +also included in the repository in the `COPYING` file. + +This utilities `iproxy` and `inetcat` are licensed under the [GNU General Public License v2.0](https://www.gnu.org/licenses/gpl-2.0.en.html). + ## Credits Apple, iPhone, iPod, and iPod Touch are trademarks of Apple Inc. -libusbmuxd is an independent software library and has not been -authorized, sponsored, or otherwise approved by Apple Inc. +This project is an independent software library and has not been authorized, +sponsored, or otherwise approved by Apple Inc. -README Updated on: 2020-06-08 +README Updated on: 2020-06-12 |