diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 183 |
1 files changed, 129 insertions, 54 deletions
@@ -1,84 +1,159 @@ # usbmuxd -## About +*A socket daemon to multiplex connections from and to iOS devices.* -A socket daemon to multiplex connections from and to iOS devices. + -## Background +## Features usbmuxd stands for "USB multiplexing daemon". This daemon is in charge of -multiplexing connections over USB to an iOS device. To users, it means -you can sync your music, contacts, photos, etc. over USB. To developers, it -means you can connect to any listening localhost socket on the device. usbmuxd -is not used for tethering data transfer which uses a dedicated USB interface as -a virtual network device. Multiple connections to different TCP ports can happen -in parallel. The higher-level layers are handled by libimobiledevice. - -When usbmuxd is running (normally started or stopped as a result of _udev_ -auto-insertion messages, or by _systemd_) it provides a socket interface in -`/var/run/usbmuxd` that is designed to be compatible with the socket interface -that is provided on macOS. - -You should also create a `usbmux` user that has access to USB devices on your -system. Alternatively, you can pass a different username using the `-U` argument. - -The daemon also manages pairing records with iOS devices and the host in -`/var/lib/lockdown` (Linux) or `/var/db/lockdown` (macOS). -Ensure proper permissions are setup for the daemon to access the directory. - -## Requirements - -Development Packages of: -* libimobiledevice -* libplist -* libusb - -Software: -* make -* autoheader -* automake -* autoconf -* libtool -* pkg-config -* gcc or clang -* udev (Linux only) +multiplexing connections over USB to an iOS device. + +To users, it means you can use various applications to interact with your +device. + +To developers, it means you can connect to any listening localhost socket on +the device. + +Some key features are: + +- **Implementation**: Open-Source implementation of proprietary usbmuxd daemon +- **Cross-Platform:** Tested on Linux, macOS, Windows and Android platforms +- **Linux**: Supports udev and systemd for automatic activation +- **Compatibility**: Supports latest device firmware releases +- **Scalability**: Supports multiple connections to different ports in parallel + +usbmuxd is not used for tethering data transfers which uses a dedicated USB +interface to act as a virtual network device. + +The higher-level layers, especially if you want to write an application to +interact with the device, are handled by [libimobiledevice](https://github.com/libimobiledevice/libimobiledevice.git). + +The low-level layer is handled by [libusbmuxd](https://github.com/libimobiledevice/libusbmuxd.git). + +## Installation / Getting started + +### Debian / Ubuntu Linux + +First install all required dependencies and build tools: +```shell +sudo apt-get install \ + build-essential \ + pkg-config \ + checkinstall \ + git \ + autoconf \ + automake \ + libtool-bin \ + libplist-dev \ + libusbmuxd-dev \ + libimobiledevice-dev \ + libimobiledevice-glue-dev \ + libusb-1.0-0-dev \ + udev +``` -Optional: -* systemd (Linux only) +If systemd is not installed and should control spawning the daemon use: +```shell +sudo apt-get install \ + systemd +``` -## Installation +Then clone the actual project repository: +```shell +git clone https://github.com/libimobiledevice/usbmuxd.git +cd usbmuxd +``` -To compile run: +Now you can build and install it: +```shell +./autogen.sh +make +sudo make install +``` +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 +./autogen.sh --prefix=/opt/local --without-preflight --without-systemd make sudo make install ``` +To output a list of available configure options use: +```bash +./autogen.sh --help +``` + +## Usage + The daemon is automatically started by udev or systemd depending on what you -have configured it on hotplug of an iOS device and exits if the last device +have configured upon hotplug of an iOS device and exits if the last device was unplugged. +When usbmuxd is running it provides a socket interface at `/var/run/usbmuxd` +that is designed to be compatible with the socket interface that is provided +on macOS. + +You should also create an `usbmux` user that has access to USB devices on your +system. Alternatively, just pass a different username using the `-U` argument. + +The daemon also manages pairing records with iOS devices and the host in +`/var/lib/lockdown` (Linux) or `/var/db/lockdown` (macOS). + +Ensure proper permissions are setup for the daemon to access the directory. + For debugging purposes it is helpful to start usbmuxd using the foreground `-f` argument and enable verbose mode `-v` to get suitable logs. -## Who/What/Where? +Please consult the usage information or manual page for a full documentation of +available command line options: +```shell +usbmuxd --help +man usbmuxd +``` + +## Contributing -* Home: https://www.libimobiledevice.org/ -* Code: `git clone https://git.libimobiledevice.org/usbmuxd.git` -* Code (Mirror): `git clone https://github.com/libimobiledevice/usbmuxd.git` -* Tickets: https://github.com/libimobiledevice/usbmuxd/issues +We welcome contributions from anyone and are grateful for every pull request! + +If you'd like to contribute, please fork the `master` branch, change, commit and +send a pull request for review. Once approved it can be merged into the main +code base. + +If you plan to contribute larger changes or a major refactoring, please create a +ticket first to discuss the idea upfront to ensure less effort for everyone. + +Please make sure your contribution adheres to: +* Try to follow the code style of the project +* Commit messages should describe the change well without being too short +* Try to split larger changes into individual commits of a common domain +* Use your real name and a valid email address for your commits + +We are still working on the guidelines so bear with us! + +## Links + +* Homepage: https://libimobiledevice.org/ +* Repository: https://git.libimobiledevice.org/usbmuxd.git +* Repository (Mirror): https://github.com/libimobiledevice/usbmuxd.git +* Issue Tracker: https://github.com/libimobiledevice/usbmuxd/issues * Mailing List: https://lists.libimobiledevice.org/mailman/listinfo/libimobiledevice-devel -* IRC: irc://irc.freenode.net#libimobiledevice * Twitter: https://twitter.com/libimobiledev +## License + +This library and utilities are licensed under the [GNU General Public License v3.0](https://www.gnu.org/licenses/gpl-3.0.en.html), +also included in the repository in the `COPYING.GPLv3` file. + ## Credits -The first usbmuxd daemon implementation was authored by Hector Martin. +The initial usbmuxd daemon implementation was authored by Hector Martin. + +Apple, iPhone, iPad, iPod, iPod Touch, Apple TV, Apple Watch, Mac, iOS, +iPadOS, tvOS, watchOS, and macOS are trademarks of Apple Inc. -Apple, iPhone, iPod, and iPod Touch are trademarks of Apple Inc. -libimobiledevice is an independent software library and has not been +usbmuxd is an independent software application and has not been authorized, sponsored, or otherwise approved by Apple Inc. -README Updated on: 2019-05-16 +README Updated on: 2022-04-04 |