usbmuxd

usbmuxd (USB Multiplexing Daemon) is a socket daemon that multiplexes connections over USB to an iOS device. It allows multiple applications to interact with a device simultaneously by connecting to listening localhost sockets on the device.

Key characteristics:

• Multiplexing: Enables parallel connections to different ports.
• Compatibility: Designed to be compatible with the socket interface provided on macOS.
• Socket Interface: When running, it provides a socket at /var/run/usbmuxd.
• Device Management: Manages pairing records in /var/lib/lockdown (Linux) or /var/db/lockdown (macOS).
• Not for Tethering: It is not used for tethering data transfers; tethering uses a dedicated USB interface acting as a virtual network device.

If you need to pass specific options to ./configure (such as a custom installation prefix or disabling specific features), you can pass them directly to ./autogen.sh.

To see all available configuration options, run:

./autogen.sh --help

Example of building with a custom prefix and disabling systemd and preflight:

./autogen.sh --prefix=/opt/local --without-preflight --without-systemd
make
sudo make install

To install usbmuxd from source on Debian or Ubuntu, follow these steps to install dependencies, clone the repository, and build the project.

1. Install Dependencies

Install the required build tools and libraries:

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

If you want systemd to control spawning the daemon, also install:

sudo apt-get install systemd

2. Build and Install

Clone the repository, run the autogen script, and compile:

git clone https://github.com/libimobiledevice/usbmuxd.git
cd usbmuxd
./autogen.sh
make
sudo make install

Automatic Lifecycle

The daemon is typically started automatically by udev or systemd when an iOS device is hotplugged and exits when the last device is unplugged.

User Permissions

You should create an usbmux user with access to USB devices. Alternatively, you can specify a different username using the -U flag.

Debugging

To debug the daemon, run it in the foreground with verbose logging enabled:

• Use -f to run in the foreground.
• Use -v for verbose mode.

Example:

usbmuxd -f -v

For a full list of command line options, use usbmuxd --help or consult the manual page with man usbmuxd.

To run usbmuxd correctly, you should create a usbmux user that has access to USB devices on your system. If you need to run the daemon as a different user, use the -U or --user flag.

Additionally, ensure the daemon has appropriate permissions to access the pairing record directory:

• Linux: /var/lib/lockdown
• macOS: /var/db/lockdown

When a device is attached, removed, or paired, the daemon can notify all clients currently in the CLIENT_LISTEN state. Use these functions to broadcast device status updates:

• client_device_add(struct device_info *dev): Notifies listening clients that a new device has been attached.
• client_device_remove(int device_id): Notifies listening clients that a device has been detached.
• client_device_paired(int device_id): Notifies listening clients that a device has been paired.

For event-driven architectures, use these functions to manage file descriptors and process incoming events:

• client_accept(int fd): Accepts a new connection on the provided file descriptor fd.
• client_get_fds(struct fdlist *list): Populates a struct fdlist with the current list of active file descriptors.
• client_process(int fd, short events): Processes events for a specific file descriptor fd with the given events mask.

The client library provides functions to update the internal representation of connected devices:

• client_device_add(struct device_info *dev): Adds a new device based on the provided struct device_info.
• client_device_remove(int device_id): Removes a device identified by its device_id.
• client_device_paired(int device_id): Marks a device with the given device_id as paired.

The client.c module provides functions to manage connections between the usbmuxd daemon and its clients. It handles accepting new connections, processing I/O events, and closing client sessions.

Key lifecycle functions:

• client_init(): Initializes the internal client list and mutex.
• client_shutdown(): Closes all active client connections and cleans up resources.
• client_accept(int listenfd): Accepts an inbound connection on the provided socket file descriptor, configures it for non-blocking mode, and creates a new mux_client instance.
• client_close(struct mux_client *client): Closes a specific client connection and removes it from the internal tracking list.

Use client_process(int fd, short events) to handle incoming or outgoing data for a specific client file descriptor. This function should be called when the event loop detects activity on a client socket.

• If the client is in the CLIENT_CONNECTED state, it delegates processing to device_client_process().
• If the client is in other states, it handles POLLIN (input buffer processing) or POLLOUT (output buffer processing) based on the events mask.